Difference between revisions of "Customer (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(Sync to latest.)
(Added customerNumber search field.)
Line 14: Line 14:
  
 
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.
 +
 +
 +
''Filter/Search'':
 +
 +
Searching will return results based on the name, account number and reference number fields. We also provide a separate query method ?referenceNumber=123456 that will return a Show on the exact customer whose reference number is as specified.
  
  
Line 87: Line 92:
  
  
''Example'':
+
''Reference Number''
 +
 
 +
The query string "referenceNumber=xx" searches for a customer with an exact reference number.
 +
 
 +
 
 +
''Examples'':
  
 
<pre>
 
<pre>
Line 113: Line 123:
 
</pre>
 
</pre>
  
 +
''Example of querying with Reference Number''
 +
 +
<pre>
 +
get '/customers?referenceNumber=49', 'text/xml'
 +
</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>
 +
</customer>
 +
</pre>
  
== Add/Edit (Reseller Only) ==
+
== Add/Edit (Reseller Only)==
  
 
''URL'':  
 
''URL'':  

Revision as of 09:06, 3 May 2010


Index (Reseller Only)

URL:

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


Description:

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


Filter/Search:

Searching will return results based on the name, account number and reference number fields. We also provide a separate query method ?referenceNumber=123456 that will return a Show on the exact customer whose reference number is as specified.


Remarks:

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


Example:

get '/customers?size=100&page=1', '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/v0/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/v0/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>
</customer>


JSON Result Example:

{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}

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>
</customer>

Add/Edit (Reseller Only)

URL:

Add: [POST] https://api.emailsrvr.com/customers
Edit: [PUT] https://api.emailsrvr.com/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/customers/(customer account number)


Description:

Deletes the account.


Example:

delete '/customers/999999', 'text/xml'