SocialOomph API for Developers

SocialOomh makes certain functions available via an Application Programming Interface (API) so that application developers can integrate their applications with SocialOomph.

The API is HTTP-based and is a RESTful resource. It is able to produce results in both XML and JSON formats.

Follow @socialoomphapi for the latest API news and announcements.

Support

To obtain API support, please submit a support ticket in the SocialOomph Support system. Select "Application Programming Interface" on the department selection page.

Method

All API calls must be authenticated POST calls. GET calls are not supported.

Authentication

Calls are authenticated using either the user's API Key, which is a 32-character alphanumeric string, or using the user's SocialOomph username and password. The user obtains her API Key by logging in to SocialOomph, and clicking the "API Key" button in the sidebar. The API Key is displayed on that page.

For authentication using the user's API Key, you must add the apikey parameter to the POST call.

For authentication using the user's SocialOomph login credentials, you must add both the username and password parameters to the POST call. Note, this is not the Basic authentication method. The credentials must be POST parameters. In other words, it is not "curl username:password http://socialoomphapi.com/object/method/format/". It is "curl http://socialoomphapi.com/object/method/format/?username=usernamevalue&password=passwordvalue".

Rate Limiting

API calls are rate limited, and are tracked by authenticating user. An authenticating user can make a maximum of 100 calls per rolling 60-minute period.

As a general rule of thumb, when you encounter a rate limit exceeded error, back off for at least 30 seconds before attempting the next call.

Calls that run into the rate limit exceeded error are also counted against the rate limit. In other words, if you keeping hitting the API even though you get rate limit exceeded, you will never get anything done because you will always be in rate limit exceeded status.

HTTP Response Codes

All calls that are understood by the API return an HTTP response code of 200 OK. However, this does not mean that the API call was valid or successful. You must check the response body to know if an error was returned, or if the requested data was returned.

On calls that the API did not understand, such as an invalid URI, it returns 404 Not Found. It could also return 500 Internal Server Error if something seriously went wrong with the web server.

Errors

On calls that are understood by the API and where the request was not successful, the API returns 200 OK and a well-formatted XML or JSON error response in the following construct.

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <error>
    <code>400</code>
    <message>No POST parameters supplied.</message>
  </error>
</resultset>

Errors that result from failure of field validation have the following construct.

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <error>
    <code>400</code>
    <message>Field validation failed.</message>
    <fields>
      <field>
        <name>account</name>
        <emsg>Account is a required field.</emsg>
      </field>
      <field>
        <name>text</name>
        <emsg>Tweet text is a required field.</emsg>
      </field>
    </fields>
  </error>
</resultset>

The name element corresponds with the name of the POST parameter.

The code in the code element mimics HTTP response codes, but remember, the actual HTTP response code on the call is 200 OK. The message element contains the reason for the error. The codes, and their broad meaning are:

400 - The request was badly formatted, meaning it was not a POST request, or the API Key was missing or invalid, or some of the other parameters did not pass field validation.
403 - The user is not authorised for the requested operation. For example, when a Free user tries to schedule a recurring tweet, or when the rate limit has been exceeded.
404 - There is no data to return. For example, if the user has no accounts, or no tweets to fetch, or no DMs to fetch.
500 - A critical component of the API is unavailable, such as the database.
502 - The API is in maintenance mode.

Return Format

You specify the desired return format as follows:

For XML: http://socialoomphapi.com/<object>/<method>/xml/

For JSON: http://socialoomphapi.com/<object>/<method>/json/

Users Object and Methods

Validate the User's Authentication Credentials

URL: http://socialoomphapi.com/users/validatekey/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).

The validatekey method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></response>
</resultset>

The response element will contain either valid or invalid.

Retrieve Authenticated User Details

URL: http://socialoomphapi.com/users/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <user>
    <first_name></first_name>
    <last_name></last_name>
    <level></level>
  </user>
</resultset>

The level element will contain Professional, Trial, or Free. If it contains Trial, an additional element trial_expire is added, which contains the time at which the trial period expires. The time is in ISO 8601 format 2009-05-29 16:02:00Z.

Accounts Object and Methods

Retrieve a List of the User's Accounts

URL: http://socialoomphapi.com/accounts/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
account - (optional) The account id to retrieve a specific account.
page - (optional) A maximum of 20 accounts are returned per call. Page starts with 1 for the first page, 2 for the second page, etc. If you omit the page parameter, then the first page is returned.

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <accounts>
    <account>
      <id></id>
      <name></name>
      <type></type>
      <automation>
        <autofollow></autofollow>
        <autounfollow></autounfollow>
        <sendwelcome></sendwelcome>
        <vetfollowers></vetfollowers>
      </automation>
    </account>
  </accounts>
</resultset>

The type element contains the account type code, which can be translated to a full description with the accounttypes object. The automation element is present only for Twitter accounts. The values of the automation elements are either TRUE or FALSE.

Account Types Object and Methods

Retrieve a Code List of Account Types

URL: http://socialoomphapi.com/accounttypes/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <accounttypes>
    <accounttype>
      <code></code>
      <description></description>
    </accounttype>
  </accounttypes>
</resultset>

It is strongly recommended that you retrieve and cache the account types locally. The types will not change. Once in a while an additional type may be added. You only need to refresh the cache when you encounter an unknown account type in the accounts object.

Tweets Object and Methods

Retrieve a List of the User's Tweets

URL: http://socialoomphapi.com/tweets/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
account - (optional) The account id to retrieve tweets for a specific account.
tweet - (optional) The tweet id to retrieve a specific tweet. You don't need to provide the account parameter when retrieving a specific tweet.
page - (optional) A maximum of 20 tweets are returned per call. Page starts with 1 for the first page, 2 for the second page, etc. If you omit the page parameter, then the first page is returned.
time_from - (optional) If specified, the list will only include tweets with a scheduled/published date-time that is greater than or equal to this parameter. Must be in the format 2009-05-29 16:02:00Z.
time_to - (optional) If specified, the list will only include tweets with a scheduled/published date-time that is less than or equal to this parameter. Must be in the format 2009-05-29 16:02:00Z.

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <tweets>
    <tweet>
      <id></id> (unique numerical id of the tweet)
      <account></account> (numerical id of the account)
      <time></time> (ISO 8601 format 2009-05-29T16:02:00+00:00)
      <text></text>
      <status></status> (Scheduled, Published, or Error)
    </tweet>
  </tweets>
</resultset>

If the status element contains Error then an additional element error_text is returned, which contains the reason for the error. The error indicates why the publishing of the tweet failed.

Add a New Scheduled Tweet

URL: http://socialoomphapi.com/tweets/add/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
account - The account id to which the tweet must be added..
text - The tweet text. Must be UTF8 encoded.
time - The scheduled time. Must be in the format 2009-05-29 16:02:00Z.
recur_freq - (optional) The recur frequency of the tweet. The codes of this field are retrieved with the recurfrequencies object. Only accepted if the user's level is Professional or Trial.
recur_stop - (optional) A number indicating after how many recurs publishing must be stopped. Only accepted if the user's level is Professional or Trial.
recur_paused - (optional) A boolean indicator to pause / unpause the publishing of a recurring tweet. Pause = 1, unpause = 0. Only accepted if the user's level is Professional or Trial.
shortenurls - (optional) A boolean indicator to tell the system to shorten the URLs in the tweet text. Shorten = 1, do not shorten = 0 (default). Authenticated bit.ly will be used if present for the user's account.

The add method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique tweet id)
</resultset>

Note that Trial and Professional users can enter spinnable tweet text in their recurring tweets. The format of a spinnable tweet (in the text POST parameter) is {option1|option2|option3|etc}. A spinnable tweet has { (open curly brace) in character position #1, } (close curly brace) in the very last character position, and the different tweet text options are separated with | (the pipe character).

Update an Existing Scheduled Tweet

URL: http://socialoomphapi.com/tweets/update/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
id - The unique tweet id..
text - The tweet text. Must be UTF8 encoded.
time - The scheduled time. Must be in the format 2009-05-29 16:02:00Z.
recur_freq - (optional) The recur frequency of the tweet. The codes of this field are retrieved with the recurfrequencies object. Only accepted if the user's level is Professional or Trial.
recur_stop - (optional) A number indicating after how many recurs publishing must be stopped. Only accepted if the user's level is Professional or Trial.
recur_paused - (optional) A boolean indicator to pause / unpause the publishing of a recurring tweet. Pause = 1, unpause = 0. Only accepted if the user's level is Professional or Trial.
shortenurls - (optional) A boolean indicator to tell the system to shorten the URLs in the tweet text. Shorten = 1, do not shorten = 0 (default). Authenticated bit.ly will be used if present for the user's account.

The update method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique tweet id)
</resultset>

Delete an Existing Tweet

URL: http://socialoomphapi.com/tweets/delete/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
id - The unique tweet id.

The delete method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique tweet id)
</resultset>

Recur Frequencies Object and Methods

Retrieve a Code List of Recur Frequencies

URL: http://socialoomphapi.com/recurfrequencies/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <recurfrequencies>
    <recurfrequency>
      <code></code>
      <description></description>
    </recurfrequency>
  </recurfrequencies>
</resultset>

It is strongly recommended that you retrieve and cache the recur frequencies locally. The frequencies will not change often. You can safely cache these for seven days before grabbing a new copy.

Direct Messages Object and Methods

Retrieve a List of the User's DMs

URL: http://socialoomphapi.com/dms/fetch/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
account - (optional) The account id to retrieve DMs for a specific account.
tweet - (optional) The DM id to retrieve a specific DM. You don't need to provide the account parameter when retrieving a specific DM.
page - (optional) A maximum of 20 DMs are returned per call. Page starts with 1 for the first page, 2 for the second page, etc. If you omit the page parameter, then the first page is returned.
time_from - (optional) If specified, the list will only include DMs with a scheduled/published date-time that is greater than or equal to this parameter. Must be in the format 2009-05-29 16:02:00Z.
time_to - (optional) If specified, the list will only include DMs with a scheduled/published date-time that is less than or equal to this parameter. Must be in the format 2009-05-29 16:02:00Z.

The fetch method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <dms>
    <dm>
      <id></id> (unique numerical id of the DM)
      <account></account> (numerical id of the account)
      <time></time> (ISO 8601 format 2009-05-29T16:02:00+00:00)
      <text></text>
      <follower></follower>
      <status></status> (Scheduled, Published, or Error)
    </dm>
  </dms>
</resultset>

If the status element contains Error then an additional element error_text is returned, which contains the reason for the error. The error indicates why the publishing of the DM failed.

Add a New Scheduled Direct Message

URL: http://socialoomphapi.com/dms/add/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
account - The account id to which the DM must be added..
text - The DM text. Must be UTF8 encoded.
time - The scheduled time. Must be in the format 2009-05-29 16:02:00Z.
follower - The Twitter username (without the @) of the DM recipient. Your application must validate that the recipient is a follower who can be DM'd.
shortenurls - (optional) A boolean indicator to tell the system to shorten the URLs in the DM text. Shorten = 1, do not shorten = 0 (default). Authenticated bit.ly will be used if present for the user's account.

The add method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique DM id)
</resultset>

Update an Existing Scheduled Direct Message

URL: http://socialoomphapi.com/dms/update/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
id - The unique DM id..
text - The DM text. Must be UTF8 encoded.
time - The scheduled time. Must be in the format 2009-05-29 16:02:00Z.
follower - The Twitter username (without the @) of the DM recipient. Your application must validate that the recipient is a follower who can be DM'd.
shortenurls - (optional) A boolean indicator to tell the system to shorten the URLs in the DM text. Shorten = 1, do not shorten = 0 (default). Authenticated bit.ly will be used if present for the user's account.

The update method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique DM id)
</resultset>

Delete an Existing Direct Message

URL: http://socialoomphapi.com/dms/delete/<format>/

POST Parameters:

The user's authentication credentials (apikey OR (username and password)).
id - The unique DM id.

The delete method returns the following:

<resultset xmlns="http://www.w3.org/TR/xptr-xmlns/">
  <response></reponse> (contains the unique DM id)
</resultset>

SocialOomph API for Developers

Follow Us

Support

Method

Authentication

Rate Limiting

HTTP Response Codes

Errors

Return Format

Users Object and Methods

Validate the User's Authentication Credentials

Retrieve Authenticated User Details

Accounts Object and Methods

Retrieve a List of the User's Accounts

Account Types Object and Methods

Retrieve a Code List of Account Types

Tweets Object and Methods

Retrieve a List of the User's Tweets

Add a New Scheduled Tweet

Update an Existing Scheduled Tweet

Delete an Existing Tweet

Recur Frequencies Object and Methods

Retrieve a Code List of Recur Frequencies

Direct Messages Object and Methods

Retrieve a List of the User's DMs

Add a New Scheduled Direct Message

Update an Existing Scheduled Direct Message

Delete an Existing Direct Message