About the SocialDraft API


  • Protocol: The transport is HTTP. The SocialDraft API tries to conform to REST principles.
  • API Endpoint: If you have not recieved your end point url upon signup, please contact us. All URLs mentioned below are relative to the endpoint. The endpoint address may change in future versions of the API.
  • API Calls: Reviews, Customers, Trending, Ratings
  • Response Format: The data returned by the API is encoded as JSON (Content-Type: application/json). The character encoding is UTF-8. Future versions of the API may introduce other formats which will be selectable through the use of Accept and Accept-Charset headers. In the current version these headers are ignored.
  • Compression: The API supports compressing response data. This can be selected through the use of the Accept-Encoding header. If your client is not in the US-East region of Amazon EC2, you will benefit from using Accept-Encoding:gzip.

Developer Requirements

1. Authentication

In order to call the API, you need to register as a developer at our developer site and accept the terms of use. You will then be issued an application ID and a key. You must either pass these with each API call in HTTP headers:

X-SocialDraft-App-ID:appid
X-SocialDraft-App-Key:appkey

or include them as URL parameters:

&appid=:appid&appkey=:appkey

If your id and key are invalid, or if you exceed your API rate limit, the server will respond with the HTTP status code 409.

2. Attribution Requirements

Whenever you display information obtained from the SocialDraft API to your users, you must give attribution to SocialDraft and the source of the API calls. The objects returned by the Reviews, Customer, Trending and Ratings API calls contain an attribution subobject which consists of the following fields:


  • html: If your application uses HTML to display data to the users, you must include the contents of the html field verbatim in a visible place near the data. You can ignore the other fields. You may not modify the HTML snippet.
  • url, text, logo: If your application is native (desktop or mobile) or otherwise doesn't use HTML, you must display the text, the logo, and a link to the URL in a visible place near the data. Clicking this should open a browser on the url. You may not modify the URL, the link text, or the logo image.
3. Plans and Rate Limits

You must choose a rate limit plan when you sign up for the API. If you'd like a higher rate limit than is offered by any of the plans, please contact us at api@socialdraft.com.

Error Codes


  • 400 - Bad Request
  • 409 - API Rate Limit Exceeded
  • 500 - Internal Server Error