Difference between revisions of "Customer (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(add Rest API Customer page)
 
(→‎Company contacts)
 
(29 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
[[PageOutline]]
+
__TOC__
  
−
== Customer ==
+
== v1 - Current ==
  
 +
=== Index (Reseller Only) ===
  
−
=== Index ===
 
  
 
''URL'':  
 
''URL'':  
  
−
  [GET] /customers
+
  [GET] <nowiki>https://api.emailsrvr.com/v1/customers</nowiki>
 +
 
 +
 
  
 
''Description'':
 
''Description'':
  
−
This operation returns the list of customers that the authenticated user has access to.
+
This operation returns the list of customers that the authenticated user has access to.
  
−
''Remarks'':
 
  
−
For the text/xml format, refer to the following schema document: [https://trac.iad.mlsrvr.com/trac/controlpanel3/browser/Api/trunk/lib/ControlPanel.Api/Schemas/Customers.xsd Customers.xsd]
+
''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'':
 
''Example'':
  
 
<pre>
 
<pre>
−
get '/customers?size=100&page=1&referenceNumber=102486', 'text/xml'
+
get '/customers?size=100&offset=10'
 +
</pre>
 +
 
 +
 
 +
''XML Result Example'':
 +
 
 +
<pre>
 +
<?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>
 
</pre>
 
</pre>
  
−
''Errors'':
 
  
−
{| border=1 class="simple"
+
''JSON Result Example'':
−
!''Description''
 
−
!''HTTP Response Code''
 
−
!''Sample Message''
 
−
|-
 
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|}
 
  
 +
<pre>
 +
{"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"}]}
 +
</pre>
  
−
=== Show ===
+
=== Show (Reseller Only) ===
  
 
''URL'':  
 
''URL'':  
  
−
  [GET] /customers/(customer account number)
+
  [GET] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>
 +
 
  
 
''Description'':
 
''Description'':
  
−
The show operation will return detailed information about the specified account.
+
The show operation will return detailed information about the specified account.
 +
 
  
 
''Remarks'':
 
''Remarks'':
  
−
The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [https://trac.iad.mlsrvr.com/trac/controlpanel3/browser/Api/trunk/lib/ControlPanel.Api/Schemas/Customer.xsd Customer.xsd]
+
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.
 +
 
 +
 
 +
''Reference Number''
 +
 
 +
The query string "referenceNumber=xx" searches for a customer with an exact reference number.
 +
 
 +
 
 +
''Examples'':
 +
 
 +
<pre>
 +
get '/customers/me'
 +
</pre>
 +
 
 +
 
 +
''XML Result Example'':
 +
 
 +
<pre>
 +
<?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>
 +
</pre>
 +
 
 +
 
 +
''JSON Result Example'':
 +
 
 +
<pre>
 +
{
 +
  "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"
 +
}
 +
</pre>
  
−
''Example'':
+
''Example of querying with Reference Number''
  
 
<pre>
 
<pre>
−
get '/customers/999999', 'text/xml'
+
get '/customers?referenceNumber=49'
 
</pre>
 
</pre>
  
−
''Errors'':
 
  
−
{| border=1 class="simple"
+
''XML Result Example'':
−
!''Description''
 
−
!''HTTP Response Code''
 
−
!''Sample Message''
 
−
|-
 
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|-
 
−
| Customer account number is invalid
 
−
| 404
 
−
| Invalid account number
 
−
|}
 
  
 +
<pre>
 +
<?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>
 +
</pre>
  
−
=== Add/Edit ===
+
=== Add/Edit (Reseller Only)===
  
 
''URL'':  
 
''URL'':  
  
−
  Add: [POST] /customers<br>  
+
  Add: [POST] <nowiki>https://api.emailsrvr.com/v1/customers</nowiki>
−
  Edit: [PUT] /customers/(customer account number)
+
  Edit: [PUT] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>
 +
 
  
 
''Description'':
 
''Description'':
  
−
Add/Edit a new sub-account. Because the customer number is not known until the customer is added, the POST data will be sent to '/customers'. An account limit that does not exist will appear as -1. Sending -1 will also set it to not exist.
+
Add or edit a new sub-account. Note that customer number is not known until the customer is added.
−
+
 
−
{| border=1 class="simple"
+
The <code>name</code> field must contain 100 characters or fewer. The <code>name</code> field cannot be null or empty and cannot begin or end with whitespace.
 +
 
 +
The <code>referenceNumber</code> must contain 20 characters or fewer.
 +
 
 +
 
 +
{| class="wikitable"
 
!''Field Name''
 
!''Field Name''
 
!''Data Type''
 
!''Data Type''
 
!''Description''
 
!''Description''
−
|-  
+
|-
 
| name
 
| name
 
| string
 
| string
−
| The customer's display name (Required for Add)
+
| The customer's display name (required for Add)
−
|-  
+
|-
 
| referenceNumber
 
| referenceNumber
 
| string
 
| string
 
| The reference number of this account
 
| 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
 
|-  
 
|-  
−
| exchangeMaxExtraStorage
+
| country
−
| integer
+
| string
−
| Megabytes of extra storage in Exchange (Only available for Edit)
+
| Account country
−
|-  
+
|-
−
| exchangeMaxMailboxes
+
| phone
−
| integer
+
| string
−
| Number of extra mailboxes in Exchange (Only available for Edit)
+
| Account phone number
−
|-  
+
|-
−
| exchangeMaxActiveSyncUsers
+
| email
−
| integer
+
| string
−
| Number of ActiveSync users in Exchange (Only available for Edit)
+
| Account email address
−
|-
 
−
| exchangeMaxBlackBerryUsers
 
−
| integer
 
−
| Number of BlackBerry Enterprise Server users in Exchange (Only available for Edit)
 
−
|-
 
−
| exchangeMaxGoodMMUsers
 
−
| integer
 
−
| Number of GoodMM sync users in Exchange (Only available for Edit)
 
−
|-
 
−
| rsEmailMaxExtraStorage
 
−
| integer
 
−
| Megabytes of extra storage in Rackspace Email (Only available for Edit)
 
−
|-
 
−
| rsEmailMaxMailboxes
 
−
| integer
 
−
| Number of extra mailboxes in Rackspace Email (Only available for Edit)
 
−
|-
 
−
| rsEmailMaxSyncUsers
 
−
| integer
 
−
| Number of Sync users in Rackspace Email (Only available for Edit)
 
−
|-
 
−
| rsEmailMaxBccArchivingUsers
 
−
| integer
 
−
| Number of BCC Archiving users in Rackspace Email (Only available for Edit)
 
 
|}
 
|}
  
Line 139: Line 232:
  
 
<pre>
 
<pre>
−
post '/customers', 'text/xml',
+
post '/customers',
 
{
 
{
−
  'name' => 'Name'  
+
  'name' => 'Name'
 
}
 
}
 
</pre>
 
</pre>
  
 
<pre>
 
<pre>
−
put '/customers/999999', 'text/xml',
+
put '/customers/999999',
 
{
 
{
−
'name' => 'NewName',
+
  'name' => 'NewName',
−
'referenceNumber' => '12345'  
+
  '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'
 
}
 
}
 
</pre>
 
</pre>
 +
  
 
''Errors'':
 
''Errors'':
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 
!''Description''
 
!''Description''
 
!''HTTP Response Code''
 
!''HTTP Response Code''
 
!''Sample Message''
 
!''Sample Message''
−
|-
+
|-
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|-  
 
 
| The name field was not specified
 
| The name field was not specified
−
| 400
+
| 400 Bad Request
 
| Missing required field: name
 
| Missing required field: name
−
|-  
+
|-
 
| The name field cannot be blank
 
| The name field cannot be blank
−
| 400
+
| 400 Bad Request
 
| Required field name cannot be empty
 
| Required field name cannot be empty
−
|-  
+
|-
−
| Names cannot start with a space
+
| Name cannot begin or end with whitespace
−
| 400
+
| 400 Bad Request
−
| Improper Customer Name
+
| Improper Customer Name: cannot begin or end with a space
−
|-  
+
|-
−
| The customer account was not found
+
| Name must contain <= 100 characters
−
| 404
+
| 400 Bad Request
−
| Customer Not Found
+
| Name too long: 100 characters or fewer
 +
|-
 +
| Reference number must contain <= 20 characters
 +
| 400 Bad Request
 +
| Reference number too long: 20 characters or fewer
 
|}
 
|}
  
  
−
=== Delete ===
+
=== Enable/Disable (Reseller Only)===
  
 
''URL'':  
 
''URL'':  
  
−
[DELETE] /customers/(customer account number)
+
<pre>
 +
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/enable
 +
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/disable
 +
</pre>
 +
 
  
 
''Description'':
 
''Description'':
  
−
Deletes the account.
+
Enables or disables the account and all services (mailboxes, sharepoint sites, etc).
  
 +
 
''Example'':
 
''Example'':
  
 
<pre>
 
<pre>
−
delete '/customers/999999', 'text/xml'
+
post '/customers/999999/disable'
 
</pre>
 
</pre>
 +
  
 
''Errors'':
 
''Errors'':
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 +
!''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] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>
 +
 
 +
 
 +
''Description'':
 +
 
 +
Deletes the account.
 +
 
 +
 
 +
''Example'':
 +
 
 +
<pre>
 +
delete '/customers/999999'
 +
</pre>
 +
 
 +
 
 +
=== Create Login Tokens ===
 +
 
 +
''URL'':
 +
 
 +
[POST] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)/loginToken</nowiki>
 +
 
 +
 
 +
''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.
 +
 
 +
{| class="wikitable"
 +
!''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'':
 +
 
 +
<pre>
 +
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}
 +
 
 +
</pre>
 +
 
 +
Create login token for virtual user 'dev_cust_limitedadmin'.
 +
 
 +
<pre>
 +
 
 +
<?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>
 +
</pre>
 +
 
 +
 
 +
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:
 +
 
 +
<pre>
 +
http://ControlPanelURL/TokenLogin.aspx?loginToken=EEB0012D8DBC2CAC26E28365D44B537FFF0D79350
 +
</pre>
 +
 
 +
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'':
 +
 
 +
<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 ===
 +
 
 +
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'':
 +
 
 +
<pre>
 +
GET '/v2/customers/999999/contacts', 'application/json'
 +
</pre>
 +
 
 +
 
 +
''Response'':
 +
 
 +
<pre>
 +
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"
 +
    }]
 +
}
 +
</pre>
 +
 
 +
===== 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 <code>ID</code> to the request path.
 +
 
 +
Locate a contact's <code>ID</code> in its <code>Items</code> array when [[view all contacts|viewing all contacts]].
 +
 
 +
 
 +
''Request'':
 +
 
 +
<pre>
 +
GET '/v2/customers/999999/contacts/4', 'application/json'
 +
</pre>
 +
 
 +
 
 +
''Response'':
 +
 
 +
<pre>
 +
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"
 +
}
 +
</pre>
 +
 
 +
 
 +
===== 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'':
 +
 
 +
<pre>
 +
GET '/v2/customers/999999/contacts?size=2&offset=2', 'application/json'
 +
</pre>
 +
 
 +
 
 +
''Response'':
 +
 
 +
<pre>
 +
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"
 +
    }]
 +
}
 +
</pre>
 +
 
 +
 
 +
==== 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'':
 +
 
 +
<pre>
 +
POST /v2/customers/9999/contacts/
 +
{
 +
    "Email": "user@example.com",
 +
    "Name": "Best Contact",
 +
    "Phone": "1235555555",
 +
    "ReceivesAlerts": false,
 +
    "ReceivesBilling": false,
 +
    "ReceivesUpdates": false,
 +
    "SecurityAnswer": "A",
 +
    "SecurityQuestion": "Q"
 +
}
 +
</pre>
 +
 
 +
 
 +
==== Update a contact (Reseller Only) ====
 +
 
 +
''Description'':
 +
 
 +
Update information for the contact you specify.
 +
 
 +
''Request'':
 +
 
 +
<pre>
 +
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"
 +
}
 +
</pre>
 +
 
 +
 
 +
''Response'':
 +
 
 +
<pre>
 +
200 OK
 +
</pre>
 +
 
 +
 
 +
==== Delete a contact (Reseller Only) ====
 +
 
 +
''Description'':
 +
 
 +
Remove a contact from the account.
 +
 
 +
An account must include at least one contact for billing. Set <code>"ReceivesBilling" : "true"</code> for any contacts permitted to handle billing-related inquiries.
 +
 
 +
''Request'':
 +
 
 +
<pre>
 +
DELETE /v2/customers/999999/contacts/4
 +
</pre>
 +
 
 +
 
 +
''Response'':
 +
 
 +
<pre>
 +
200 OK
 +
</pre>
 +
 
 +
 
 +
==== Errors for GET requests ====
 +
 
 +
 
 +
{| class="wikitable"
 
!''Description''
 
!''Description''
 
!''HTTP Response Code''
 
!''HTTP Response Code''
 
!''Sample Message''
 
!''Sample Message''
−
|-  
+
|-
−
| Format is invalid
+
| Invalid method
−
| 406
+
| 404 Not Found
−
| Invalid format
+
| Make sure the URL is correct.
−
|-  
+
|}
−
| The customer account was not found
+
 
−
| 404
+
 
−
| Customer Not Found
+
==== Errors for DELETE requests ====
 +
 
 +
 
 +
{| class="wikitable"
 +
!''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 ====
  
  
−
{{TracNotice|{{PAGENAME}}}}
+
{| class="wikitable"
 +
!''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 <code>application/json</code>.
 +
|-
 +
| 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.
 +
|}

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"