Customer (Rest API)

From Rackspace Email & Apps API
Revision as of 14:32, 19 October 2015 by Zach7981 (talk | contribs) (Added fields for customer information.)
Jump to: navigation, search

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.


Remarks:

For the text/xml format, refer to the following schema document: CustomerList.xsd


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:

Returns detailed information about the specified account.


Remarks:

To show detailed information for the account that is logged in instead of a customer's account, use "me" in the place of the customer account number. For example:

'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/Edit a new sub-account. Note that customer number is not known until the customer is added.


Field Name Data Type Description
name string The customer's display name (Required for Add)
referenceNumber string The reference number of this account


Example: 

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

put '/customers/999999', 'text/xml',
{
 'name' => 'NewName',
 'referenceNumber' => '12345'
}


Errors:

Description HTTP Response Code Sample Message
The name field was not specified 400 Missing required field: name
The name field cannot be blank 400 Required field name cannot be empty
Names cannot start with a space 400 Improper Customer Name

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=698"