Developers & API: Getting Started

The Opt It Mobile API is included with your Opt It Mobile account. The information below will give you the foundation to start using the REST-based API.

Create an Account

First thing you will need to do is create an Opt It Mobile account. If you do not have an account, please sign up for an account first. This account will allow you to grant permissions necessary to access the Opt It Mobile API.

Assign "Mobile API Access" Role

Once you have an Opt It Mobile account, you will need to grant the "Mobile API Access" role to your user inside your account in order to authenticate. You will use the username and password of this user as the crendetials for authentication. You can add this role by going to Account -> Manager Users and editing the user. Only users with this role can authenticate via the Opt It Mobile API. In addition, users with the Mobile API Access role can only access resources of the keywords they have been assigned. If an authenticated user tries to access a resource for keywords they do not have permissions, they will receive a 401 "Unauthorized" error.

Authentication

All REST API calls require the user to authenticate via Basic Authentication. You must use a valid username and password and the user must have the Mobile API Access role assigned to them. Currently, this is the only authentication method that is supported.

RESTful Resource

The Opt It Mobile API follows the design principles of Representational State Transfer(REST). You can change the format in which you get results by changing the extenstion in your request. Currently, XML and JSON are supported for most methods, but please check each method call for specific details.

Pararmeters & Paging

Certain API methods have an optional parameters that can be used to filter the result set. The parameters are specified with each method where appropriate. In addition, a page parameter can be used to page through results.

Encoding

The Opt It Mobile API supports UTF-8 encoding. Please URL encode all parameters when making requests.

HTTP Response Codes and Errors

The Opt It Mobile API will return one of the following response codes with each request.

• 200 OK: Successfully executed the request.
• 400 Bad Request: The request was invalid. Generic client side error when another specific error is not appropriate. An error message will be included in the response.
• 401 Unauthorized: Authentication failed.
• 403 Forbidden: The client authenticated properly, but does not have the proper permissions to access the resource.
• 404 Not Found: If the resource the client requested does not exist or if they do not have permissions for that resource.
• 409 Conflict: This error will be used in future releases when the client is creating a resource that is already in use.
• 500 Internal Server Error: Generic server error response. Please email support with this error so we can look into it.
• 503 Service Unavailable: The HTTP server is up, but the service is not responding.

For requests that encounter an error, an error will be returned in your requested format. An XML error would be returned in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>NoSuchResource</code>
    <resource>/message/12345/update.xml</resource>
    <message>The resource does not exist</message>
    <request_id>abe3f028-d666-4896-a0b0-cf41b77b1dfa</request_id>
</error>