Difference between revisions of "Customer (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(Undo revision 698 by Zach7981 (talk))
Line 20: Line 20:
  
 
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.
 
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.
−
 
−
 
−
''Remarks'':
 
−
 
−
For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/Schemas/CustomerList.xsd CustomerList.xsd]
 
  
  
Line 113: Line 108:
 
   <accountNumber>460182</accountNumber>
 
   <accountNumber>460182</accountNumber>
 
   <referenceNumber>49</referenceNumber>
 
   <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>
 
</customer>
 
</pre>
 
</pre>
Line 120: Line 123:
  
 
<pre>
 
<pre>
−
{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}
+
{
 +
  "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>
 
</pre>
  
Line 139: Line 154:
 
   <accountNumber>460182</accountNumber>
 
   <accountNumber>460182</accountNumber>
 
   <referenceNumber>49</referenceNumber>
 
   <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>
 
</customer>
 
</pre>
 
</pre>
Line 152: Line 175:
 
''Description'':
 
''Description'':
  
−
Add/Edit a new sub-account. Note that customer number is not known until the customer is added.
+
Add or edit a new sub-account. Note that customer number is not known until the customer is added.
 +
 
 +
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.
  
  
Line 162: Line 189:
 
| 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
 +
|-
 +
| country
 +
| string
 +
| Account country
 +
|-
 +
| phone
 +
| string
 +
| Account phone number
 +
|-
 +
| email
 +
| string
 +
| Account email address
 
|}
 
|}
  
Line 182: Line 241:
 
put '/customers/999999', 'text/xml',
 
put '/customers/999999', 'text/xml',
 
{
 
{
−
'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>
Line 196: Line 263:
 
|-
 
|-
 
| 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
 +
|-
 +
| 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'':
 +
 
 +
<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'':
 +
 
 +
Enables or disables the account and all services (mailboxes, sharepoint sites, etc).
 +
 
 +
 +
''Example'':
 +
 
 +
<pre>
 +
post '/customers/999999/disable'
 +
</pre>
 +
 
 +
 
 +
''Errors'':
 +
 
 +
{| 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) ===
 
=== Delete (Reseller Only) ===

Revision as of 10:21, 21 October 2015

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', 'text/xml'


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. For text/xml format, refer to the following schema document: Customer.xsd


Reference Number

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


Examples: 

get '/customers/me', 'text/xml'


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', 'text/xml'


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', 'text/xml',
{
 'name' => 'Name'
}

put '/customers/999999', 'text/xml',
{
  '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', 'text/xml'


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'}, 'text/xml'

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).

Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Customer_(Rest_API)&oldid=700"