Difference between revisions of "Customer (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(→‎Company contacts)
 
(3 intermediate revisions by 2 users not shown)
Line 25: Line 25:
  
 
<pre>
 
<pre>
−
get '/customers?size=100&offset=10', 'text/xml'
+
get '/customers?size=100&offset=10'
 
</pre>
 
</pre>
  
Line 84: Line 84:
 
To do the show operation on the account that is logged in instead of a customer's account, use "me" in the place of the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v1/customers/me'</nowiki>.
 
To do the show operation on the account that is logged in instead of a customer's account, use "me" in the place of the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v1/customers/me'</nowiki>.
  
−
The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/Schemas/Customer.xsd Customer.xsd]
+
The show operation only supports the GET HTTP verb.
  
  
Line 95: Line 95:
  
 
<pre>
 
<pre>
−
get '/customers/me', 'text/xml'
+
get '/customers/me'
 
</pre>
 
</pre>
  
Line 141: Line 141:
  
 
<pre>
 
<pre>
−
get '/customers?referenceNumber=49', 'text/xml'
+
get '/customers?referenceNumber=49'
 
</pre>
 
</pre>
  
Line 232: Line 232:
  
 
<pre>
 
<pre>
−
post '/customers', 'text/xml',
+
post '/customers',
 
{
 
{
 
  'name' => 'Name'
 
  'name' => 'Name'
Line 239: Line 239:
  
 
<pre>
 
<pre>
−
put '/customers/999999', 'text/xml',
+
put '/customers/999999',
 
{
 
{
 
   'name' => 'NewName',
 
   'name' => 'NewName',
Line 338: Line 338:
  
 
<pre>
 
<pre>
−
delete '/customers/999999', 'text/xml'
+
delete '/customers/999999'
 
</pre>
 
</pre>
  
Line 376: Line 376:
  
 
<pre>
 
<pre>
−
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}, 'text/xml'
+
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}
  
 
</pre>
 
</pre>
Line 413: Line 413:
  
 
== v2 - Current ==
 
== v2 - Current ==
 +
 +
=== Company Invoices ===
 +
 +
The paths in this section allow you to view a list of invoices, and download a CSV of the line items of a particular invoice.
 +
 +
==== View Invoices ====
 +
 +
''Description'':
 +
 +
View a list of invoices for an account in reverse chronological order (most recent first).
 +
 +
 +
''Request'':
 +
 +
<pre>
 +
GET '/v2/customers/999999/invoices', 'application/json'
 +
</pre>
 +
 +
''Response'':
 +
 +
<pre>
 +
200 OK
 +
{
 +
    "Size": 50,
 +
    "Offset": 0,
 +
    "Total": 1,
 +
    "Items": [{
 +
        "InvoiceId": "123",
 +
        "InvoiceDate": "2017-12-07T00:00:00",
 +
        "InvoiceType": "Billing",
 +
        "TotalDue": "1122.55",
 +
        "IsPaid": true,
 +
        "CsvAvailable": true
 +
    }]
 +
}
 +
</pre>
 +
 +
===== Request parameters =====
 +
 +
- ''Size'': The number of invoices returned to GET requests. The default value is 50.
 +
 +
- ''Offset'': Indicates an offset at which to return invoices to GET requests. The default value is 0.
 +
 +
- ''Total'': Indicates the total number of invoices for the account.
 +
 +
===== CsvAvailable =====
 +
 +
If CsvAvailable is true, then you can use the CSV path (see just below) to retrieve a CSV of line items for this invoice.
 +
 +
==== Invoice Line Items ====
 +
 +
''Description'':
 +
 +
Download a CSV of line items for a specific invoice. You must pass a valid invoice ID in the path.
 +
 +
 +
''Request'':
 +
 +
<pre>
 +
GET '/v2/customers/999999/invoices/123123', 'application/json'
 +
</pre>
 +
Where 123123 is the invoice ID.
 +
 +
NOTE! The content-type returned for this route will always be 'text/csv'.
 +
 +
NOTE! CSV files are only available for invoices starting around July 2017. If a CSV is not available, this route will return a 404.
 +
 +
''Response'':
 +
 +
<pre>
 +
200 OK
 +
Account No,Reference No,Domain,Product,Type,Service Start,Service End,Term Committed Usage,Current Usage,Usage Change,Months,Rate,Charge
 +
1371592,"","MyDomain.com","Outlook",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
 +
1371592,"","MyDomain.com","Hosted Exchange",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,7,140
 +
1371592,"","MyDomain.com","Hosted Exchange ActiveSync",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
 +
1371592,"","MyDomain.com","Hosted Exchange Extra Storage",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,150,150,150,1,0,0
 +
1386010,"","MyOtherDomain","Office 365 Business Essentials",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,31,31,31,1,7,217
 +
1386010,"","MyOtherDomain","Office 365 Business Essentials",Upgrade,11/6/2017 7:54:44 PM,11/30/2017 11:59:59 PM,29,31,2,0.81,7,11.34
 +
1386010,"","MyOtherDomain","Office 365 Business Premium",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,39,39,39,1,14,546
 +
</pre>
 +
 +
  
 
=== Company contacts ===
 
=== Company contacts ===
Line 419: Line 501:
  
  
−
==== View contacts ====
+
==== View contacts (Reseller Only) ====
  
 
''Description'':
 
''Description'':
Line 456: Line 538:
 
</pre>
 
</pre>
  
−
===== Request parameters =====
+
===== Request parameters (Reseller Only) =====
  
 
- ''Size'': The number of contacts returned to GET requests. The default value is 50.  
 
- ''Size'': The number of contacts returned to GET requests. The default value is 50.  
Line 465: Line 547:
  
  
−
===== Alerts, Billing, and Updates =====
+
===== Alerts, Billing, and Updates (Reseller Only) =====
  
 
- ''ReceivesAlerts'': Indicates whether a contact receives account alerts.
 
- ''ReceivesAlerts'': Indicates whether a contact receives account alerts.
Line 474: Line 556:
  
  
−
===== View a specific contact =====
+
===== View a specific contact (Reseller Only) =====
  
 
''Description'':  
 
''Description'':  
Line 509: Line 591:
  
  
−
===== View a range of contacts at an offset =====
+
===== View a range of contacts at an offset (Reseller Only) =====
  
 
''Description'':
 
''Description'':
Line 559: Line 641:
  
  
−
==== Add a contact ====
+
==== Add a contact (Reseller Only) ====
  
 
''Description'':
 
''Description'':
Line 584: Line 666:
  
  
−
==== Update a contact ====
+
==== Update a contact (Reseller Only) ====
  
 
''Description'':
 
''Description'':
Line 614: Line 696:
  
  
−
==== Delete a contact ====
+
==== Delete a contact (Reseller Only) ====
  
 
''Description'':
 
''Description'':

Latest revision as of 13:24, 5 June 2019

v1 - Current

Index (Reseller Only)

URL: 

[GET] https://api.emailsrvr.com/v1/customers


Description:

This operation returns the list of customers that the authenticated user has access to.


Filter/Search:

Search parameter 'startswith' and 'contains' will try to find the result in customer name, account number and reference number. We also provide a separate query method ?referenceNumber=123456 that will return a Show on the exact customer whose reference number is as specified. This query method only returns details for sub-accounts.


Example: 

get '/customers?size=100&offset=10'


XML Result Example: 

<?xml version="1.0" encoding="utf-8"?>
<customerList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customerList">
  <offset>0</offset>
  <size>50</size>
  <total>3</total>
  <customers>
    <customer>
      <name>API Customer 17</name>
      <accountNumber>460182</accountNumber>
      <referenceNumber>49</referenceNumber>
    </customer>
    <customer>
      <name>API Customer 39</name>
      <accountNumber>460181</accountNumber>
      <referenceNumber>23</referenceNumber>
    </customer>
    <customer>
      <name>API Customer 50</name>
      <accountNumber>460183</accountNumber>
      <referenceNumber>10</referenceNumber>
    </customer>
  </customers>
</customerList>


JSON Result Example: 

{"offset":0,"size":50,"total":3,"customers":
[{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"},
{"name":"API Customer 39","accountNumber":"460181","referenceNumber":"23"},
{"name":"API Customer 50","accountNumber":"460183","referenceNumber":"10"}]}

Show (Reseller Only)

URL: 

[GET] https://api.emailsrvr.com/v1/customers/(customer account number)


Description:

The show operation will return detailed information about the specified account.


Remarks:

To do the show operation on the account that is logged in instead of a customer's account, use "me" in the place of the customer account number i.e. 'https://api.emailsrvr.com/v1/customers/me'.

The show operation only supports the GET HTTP verb.


Reference Number

The query string "referenceNumber=xx" searches for a customer with an exact reference number.


Examples: 

get '/customers/me'


XML Result Example: 

<?xml version="1.0" encoding="utf-8"?>
<customer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customer">
  <name>API Customer 17</name>
  <accountNumber>460182</accountNumber>
  <referenceNumber>49</referenceNumber>
  <addressLine1>555 Address</addressLine1>
  <addressLine2>Suite 555</addressLine2>
  <city>Austin</city>
  <state>TX</state>
  <zip>78703</zip>
  <country>US</country>
  <phone>1-555-555-5555</phone>
  <email>user@example.com</email>
</customer>


JSON Result Example: 

{
  "name":"API Customer 17",
  "accountNumber":"460182",
  "referenceNumber":"49",
  "addressLine1":"555 Address",
  "addressLine2":"Suite 555",
  "city":"Austin",
  "state":"Texas",
  "zip":"78703",
  "country":"USA",
  "phone":"1-555-555-5555",
  "email":"user@example.com"
}

Example of querying with Reference Number 

get '/customers?referenceNumber=49'


XML Result Example: 

<?xml version="1.0" encoding="utf-8"?>
<customer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customer">
  <name>API Customer 17</name>
  <accountNumber>460182</accountNumber>
  <referenceNumber>49</referenceNumber>
  <addressLine1>555 Address</addressLine1>
  <addressLine2>Suite 555</addressLine2>
  <city>Austin</city>
  <state>TX</state>
  <zip>78703</zip>
  <country>US</country>
  <phone>1-555-555-5555</phone>
  <email>user@example.com</email>
</customer>

Add/Edit (Reseller Only)

URL: 

Add: [POST] https://api.emailsrvr.com/v1/customers
Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)


Description:

Add or edit a new sub-account. Note that customer number is not known until the customer is added.

The name field must contain 100 characters or fewer. The name field cannot be null or empty and cannot begin or end with whitespace.

The referenceNumber must contain 20 characters or fewer.


Field Name Data Type Description
name string The customer's display name (required for Add)
referenceNumber string The reference number of this account
addressLine1 string Street address for the account
addressLine2 string Additional address information (building, suite, etc.)
city string Account city
state string Account state
zip string Account ZIP code
country string Account country
phone string Account phone number
email string Account email address


Example: 

post '/customers',
{
 'name' => 'Name'
}

put '/customers/999999',
{
  'name' => 'NewName',
  'referenceNumber' => '12345'
  'addressLine1':'555 Address',
  'addressLine2':'Suite 555',
  'city':'Austin',
  'state':'Texas',
  'zip':'78703',
  'country':'USA',
  'phone':'1-555-555-5555',
  'email':'user@example.com'
}


Errors:

Description HTTP Response Code Sample Message
The name field was not specified 400 Bad Request Missing required field: name
The name field cannot be blank 400 Bad Request Required field name cannot be empty
Name cannot begin or end with whitespace 400 Bad Request Improper Customer Name: cannot begin or end with a space
Name must contain <= 100 characters 400 Bad Request Name too long: 100 characters or fewer
Reference number must contain <= 20 characters 400 Bad Request Reference number too long: 20 characters or fewer


Enable/Disable (Reseller Only)

URL: 

[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/enable
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/disable


Description:

Enables or disables the account and all services (mailboxes, sharepoint sites, etc).


Example: 

post '/customers/999999/disable'


Errors:

Description HTTP Response Code Sample Message
You are either trying to enable/disable an account which does not belong to you or the admin associated with your api key does not have the correct role(s) to perform this action. 403 Not authorized
You have made too many recent requests to perform this action. You are allowed to perform this action only one time in a 5 minute sliding window. 403 Exceeded request limits


Delete (Reseller Only)

URL: 

[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)


Description:

Deletes the account.


Example: 

delete '/customers/999999'


Create Login Tokens

URL:

[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/loginToken


Description:

Generate a login token using which a customer can use to SSO into the Control Panel.

Login tokens can be generated for two kinds of users: virtual and non-virtual. The distinction between the two users is that a virtual user gets the administrator's privileges when SSOed into the Control Panel. On the other hand, the non-virtual user gets only as much privileges as are given to him/her when his/her account was created.

Field Name Data Type Description
userName string The name for which login token needs to be created.
virtualUser string A flag indicating whether the user for whom the login token needs to be generated is virtual or non-virtual. Valid values: true/false. When set to true, the userName is treated as a virtual user. When set to false, the userName is treated as a non-virtual user. A non-virtual user must be an existing admin user.


Example: 

post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}

Create login token for virtual user 'dev_cust_limitedadmin'. 


<?xml version="1.0" encoding="utf-8"?>

<loginToken xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 

xmlns="urn:xml:loginToken">

  <user>dev_cust_limitedadmin_460896_vu</user>

  <token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

  <dateCreated>6/11/2010 10:53:46 AM</dateCreated>

</loginToken>


The login token is valid for ten minutes after its creation. The "dateCreated" field indicates the time when the login token is created.

Using the above created login token the customer with account number 460896 can SSO into the Control Panel using the following URL: 

http://ControlPanelURL/TokenLogin.aspx?loginToken=EEB0012D8DBC2CAC26E28365D44B537FFF0D79350

A customer can also use the login token to login on their private label control panel (E.g.: cp.mydomain.com/logintokens.aspx).

v2 - Current

Company Invoices

The paths in this section allow you to view a list of invoices, and download a CSV of the line items of a particular invoice.

View Invoices

Description:

View a list of invoices for an account in reverse chronological order (most recent first).


Request: 

GET '/v2/customers/999999/invoices', 'application/json'

Response: 

200 OK
{
    "Size": 50,
    "Offset": 0,
    "Total": 1,
    "Items": [{
        "InvoiceId": "123",
        "InvoiceDate": "2017-12-07T00:00:00",
        "InvoiceType": "Billing",
        "TotalDue": "1122.55",
        "IsPaid": true,
        "CsvAvailable": true
    }]
}
Request parameters

- Size: The number of invoices returned to GET requests. The default value is 50.

- Offset: Indicates an offset at which to return invoices to GET requests. The default value is 0.

- Total: Indicates the total number of invoices for the account.

CsvAvailable

If CsvAvailable is true, then you can use the CSV path (see just below) to retrieve a CSV of line items for this invoice.

Invoice Line Items

Description:

Download a CSV of line items for a specific invoice. You must pass a valid invoice ID in the path.


Request: 

GET '/v2/customers/999999/invoices/123123', 'application/json'

Where 123123 is the invoice ID.

NOTE! The content-type returned for this route will always be 'text/csv'.

NOTE! CSV files are only available for invoices starting around July 2017. If a CSV is not available, this route will return a 404.

Response: 

200 OK
Account No,Reference No,Domain,Product,Type,Service Start,Service End,Term Committed Usage,Current Usage,Usage Change,Months,Rate,Charge
1371592,"","MyDomain.com","Outlook",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
1371592,"","MyDomain.com","Hosted Exchange",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,7,140
1371592,"","MyDomain.com","Hosted Exchange ActiveSync",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
1371592,"","MyDomain.com","Hosted Exchange Extra Storage",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,150,150,150,1,0,0
1386010,"","MyOtherDomain","Office 365 Business Essentials",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,31,31,31,1,7,217
1386010,"","MyOtherDomain","Office 365 Business Essentials",Upgrade,11/6/2017 7:54:44 PM,11/30/2017 11:59:59 PM,29,31,2,0.81,7,11.34
1386010,"","MyOtherDomain","Office 365 Business Premium",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,39,39,39,1,14,546


Company contacts

The paths in this section allow you to manage company contacts. Company contacts have authorization to contact Support with questions about this account.


View contacts (Reseller Only)

Description:

View all contacts for an account.


Request: 

GET '/v2/customers/999999/contacts', 'application/json'


Response: 

200 OK
{
    "Size": 50,
    "Offset": 0,
    "Total": 1,
    "Items": [{
        "CustomerNumber": "999999",
        "Email": "user@example.com",
        "Id": "1",
        "Name": "Contact first - Ellie",
        "Phone": "1235555555",
        "ReceivesAlerts": true,
        "ReceivesBilling": true,
        "ReceivesUpdates": true,
        "SecurityAnswer": "A",
        "SecurityQuestion": "Q"
    }]
}
Request parameters (Reseller Only)

- Size: The number of contacts returned to GET requests. The default value is 50.

- Offset: Indicates an offset at which to return contacts to GET requests. The default value is 0.

- Total: Indicates the total number of contacts for the account.


Alerts, Billing, and Updates (Reseller Only)

- ReceivesAlerts: Indicates whether a contact receives account alerts.

- ReceivesBilling: Authorizes a contact to receive billing information and inquiries. An account must have at least one billing contact.

- ReceivesUpdates: Indicates whether a contact receives account update notifications.


View a specific contact (Reseller Only)

Description:

View a specific contact by adding a contact's ID to the request path.

Locate a contact's ID in its Items array when viewing all contacts.


Request: 

GET '/v2/customers/999999/contacts/4', 'application/json'


Response: 

200 OK
{
    "CustomerNumber": "999999",
    "Email": "user@example.com",
    "Id": "4",
    "Name": "Contact first - Ellie",
    "Phone": "1235555555",
    "ReceivesAlerts": true,
    "ReceivesBilling": true,
    "ReceivesUpdates": true,
    "SecurityAnswer": "A",
    "SecurityQuestion": "Q"
}


View a range of contacts at an offset (Reseller Only)

Description:

Include Size and Offset in the URL of GET requests to view a range of contacts at an offset.


Request: 

GET '/v2/customers/999999/contacts?size=2&offset=2', 'application/json'


Response: 

200 OK
{
    "Size": 2,
    "Offset": 2,
    "Total": 4,
    "Items": [{
        "CustomerNumber": "999999",
        "Email": "user3@example.com",
        "Id": "3",
        "Name": "Contact first - Ellie",
        "Phone": "1235555555",
        "ReceivesAlerts": true,
        "ReceivesBilling": true,
        "ReceivesUpdates": true,
        "SecurityAnswer": "A",
        "SecurityQuestion": "Q"
    },
    {
        "CustomerNumber": "999999",
        "Email": "user4@example.com",
        "Id": "4",
        "Name": "Contact after hours - Samir",
        "Phone": "1235555555",
        "ReceivesAlerts": false,
        "ReceivesBilling": false,
        "ReceivesUpdates": false,
        "SecurityAnswer": "A",
        "SecurityQuestion": "Q"
    }]
}


Add a contact (Reseller Only)

Description:

Create a new contact.

Creating a new contact requires all contact fields to be populated. See the following request body for a complete list.

Request: 

POST /v2/customers/9999/contacts/
{
    "Email": "user@example.com",
    "Name": "Best Contact",
    "Phone": "1235555555",
    "ReceivesAlerts": false,
    "ReceivesBilling": false,
    "ReceivesUpdates": false,
    "SecurityAnswer": "A",
    "SecurityQuestion": "Q"
}


Update a contact (Reseller Only)

Description:

Update information for the contact you specify.

Request: 

PUT /v2/customers/999999/contacts/4
{
    "Email": "user@example.com",
    "Name": "Best Contact",
    "Phone": "1235555555",
    "ReceivesAlerts": false,
    "ReceivesBilling": false,
    "ReceivesUpdates": false,
    "SecurityAnswer": "A",
    "SecurityQuestion": "Q"
}


Response: 

200 OK


Delete a contact (Reseller Only)

Description:

Remove a contact from the account.

An account must include at least one contact for billing. Set "ReceivesBilling" : "true" for any contacts permitted to handle billing-related inquiries.

Request: 

DELETE /v2/customers/999999/contacts/4


Response: 

200 OK


Errors for GET requests

Description HTTP Response Code Sample Message
Invalid method 404 Not Found Make sure the URL is correct.


Errors for DELETE requests

Description HTTP Response Code Sample Message
Attempting to delete the last primary or billing contact 400 Bad Request There must be at least one billing contact and one primary contact. (A single contact can be both.)


Errors for PUT and POST requests

Description HTTP Response Code Sample Message
POST body is empty 400 Bad Request Payload must be a valid JSON object. Make sure the POST body contains content.
Wrong content type 400 Bad Request Payload must be a valid JSON object. Verify that the content type is application/json.
Unable to add a new contact or administrator. 400 Bad Request Contact/Administrator limit reached.
Missing contact name 400 Bad Request Contact name cannot be empty.
Missing or invalid email address 400 Bad Request Please enter a valid email address.
No security question specified 400 Bad Request Security question cannot be empty.
No security answer specified 400 Bad Request Security answer cannot be empty.
Admin does not have permission to add, change, or remove contacts 403 Not Authorized Unauthorized.
Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Customer_(Rest_API)&oldid=769"