Our goal is to make working with the RealSatisfied API as simple a possible for developers. With that in mind we have made available a developers sandbox complete with a test account. The sandbox is designed to expose all of the detail for requests and responses for each available resource within the API.

The sandbox is available here

The RealSatisfied API manages authentication using HTTP 'Basic' authentication. Two parts are required; api_user and api_key. Every request must include the Authorization HTTP header.

Below is an example using the api_user and api_key through curl:

curl -u {api_user}:{api_key} ... https://api.realsatisfied.com/v1/invitations/1234.json
				

Please note: The RealSatisfied API only responds to requests made via SSL/https (https://api.realsatisfied.com/v1/).

Use your api_user as the username, and api_key as the password. Your api_user & api_key can be found by logging into your RealSatisfied account, clicking on the "Admin" menu, and then selecting the API tab.

You will need to have the API enabled for your Office, if you are in a multi-office environment this will be managed at the corporate level.

When you're using the API, it's always through special API user (api_user) for your office. The api_user does not show up in you Team Members list within RealSatisfied and does not count towards you number of Team Members for Billing.

Remember that anyone who has your api_user and api_key can see and change everything in the RealSatisfied Office that the api_user and api_key relates to. You should apply the same protection to these keys as you would your username and password. If you suspect that your api_key has been compromised, you can regenerate it at any time from the 'API' tab under 'Admin' in RealSatisfied. Note this will result in any application using the original api_key no longer being able to authenticate to your RealSatisfied API.

The only information required in the HTTP header, by the RealSatisfied API as part of a request is the Authorization HTTP header. Any other headers required by the HTTP protocol standards should also be included.

The RealSatisfied API uses {resource}.{format} notation to specify request and response format - the API currently speaks two languages JSON and XML. An example of each using curl is shown below.

curl -u X0X0X0:1234a2345b3456c4567 https://api.realsatisfied.com/v1/invitations/1234.json
curl -u X0X0X0:1234a2345b3456c4567 https://api.realsatisfied.com/v1/invitations/1234.xml
				

Reading through the API
The RealSatisfied API has two types of actions for reading: Show and list. Show returns a single record and list returns a collection. Each of these actions are requested through GET.

A few examples of reading with curl where {#id} represents the id of a specific record:

curl -u X0X0X0:1234a2345b3456c4567 https://api.realsatisfied.com/v1/accounts.xml
curl -u X0X0X0:1234a2345b3456c4567 \
https://api.realsatisfied.com/v1/accounts/{#id}/invitations.json
curl -u X0X0X0:1234a2345b3456c4567 https://api.realsatisfied.com/v1/invitations/{#id}.xml
				

Writing through the API
When you're creating and updating resources, you'll be sending XML or JSON into RealSatisfied. The system identifies the format of the data you are sending with your request by the .{format} notation described above. Then you just include the XML|JSON of the resource in the body of your request.

An example of creating a new resource:

curl -u X0X0X0:1234a2345b3456c4567 \
-d '<invitations><target_email>...</target_email>...</invitations>' \
https://api.realsatisfied.com/v1/accounts/{#id}/invitations.xml
				

The response to a successful creation is the status code "200 OK". You can get the URL of the new resource in the Location header (such that you know where to update your new resource in the future). We also include the complete XML|JSON for the final resource in the response. The appropriate Content-type header (application/xml|application/json) relative to your requested data format is included with the response.

Updating resources is done through the PUT verb and against the URL of the resource you want to update. An example:

curl -u X0X0X0:1234a2345b3456c4567 -X PUT \
-d '<accounts><phone>(555) 231 2145</phone></accounts>' \
https://api.realsatisfied.com/v1/accounts/{#id}.xml

The response to a successful update is "200 OK".

Dealing with failure
If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:

HTTP/1.1 404 The record could not be found
Date: Thu, 12 Jan 2012 13:56:02 GMT
...
				

Note that, in general, if a request results in a successful operation (like a successful query, insert, or update) "200 OK" status code will be returned along with any detail in the body of the response.

Any request to the API that returns a collection eg https://api.realsatisfied.com/accounts.json will return three attributes related to paging; limit, offset & total_items.

limit
Any request to the API that returns a collection eg

https://api.realsatisfied.com/v1/accounts.json

will have a preset limit of 20 applied, returning 20 items. The limit can be set to a value between 1 and 100.

https://api.realsatisfied.com/v1/accounts.json?limit=25

will return the first 25 items as the limit has been modified to 25 and the default offset of 0 is applied

offset
Any request to the API that returns a collection eg

https://api.realsatisfied.com/v1/accounts.json

will have a preset offset of 0 returning n items as defined by limit starting at the first item.

To return the next page of items set the offset to offset + limit eg

https://api.realsatisfied.com/v1/accounts.json?offset=75&limit=25

will return the 4th page of items as the offset is now set to 75 with the limit of 25 applied.

total_items
this is the total number of items in the collection resulting from the request (ignoring the limit and offset) an example of what is returned

https://api.realsatisfied.com/v1/surveys.xml?limit=2&offset=0

returns

<response>
  <offset>0</offset>
  <limit>2</limit>
  <total_items>5</total_items>
  <surveys>
    <survey>
      <survey_type>US_SELLER</survey_type>
      <name>Seller Satisfaction Survey</name>
    </survey>
    <survey>
      <survey_type>US_BUYER</survey_type>
      <name>Buyer Satisfaction Survey</name>
    </survey>
  </surveys>
</response>

In some instances the client you may be using may not support all of the verbs used by a REST API (GET, POST, PUT & DELETE).
By including the method variable in your request the method supplied shall override the method supplied in the HTTP header.

POST https://api.realsatisfied.com/v1/accounts/100001.json?method=put

is the equivalent of

PUT https://api.realsatisfied.com/v1/accounts/100001.json

You can perform up to 500 requests per 10 second period from the same IP address for the same api_user. If you exceed this limit, you'll get a 503 - Service Unavailable response for subsequent requests. Check the Retry-After header to see how many seconds to wait before trying again.

As the API is not associated with a particular Team Member a specific API notifications email address is required to send messages relating API generated actions e.g. Bounced Invitation Notifications

By default the Account Owners email address is used, however this can be updated to any address you like on a per office basis.

Taking the example of Bounced Invitations Notifications - whenever a RealSatisfied invitation results in an email bounce, a message is sent to the creator of the Invitation advising of the bounce and prompting them to try another address.

For Invitations created with the API these messages are sent to the Email Address for API Notifications set for each office - by default it is the Account Owners email.

You may wish to alter this to an address for a person in each office that can update bounced addresses for that office. The address can be set on the API tab under Admin in each office.