API Overview

The Oktopost API provides programmatic access to read and write Oktopost data. This article describes the resources that make up the API. If you have any issue, question or request please contact us.

Schema

API access is available using HTTPS only from the api.oktopost.com domain. Data is sent back to the client in a standard JSON format.

All timestamps are sent and received in UTC EPOCH (number of seconds since January 1st 1970, UTC timezone).

Authentication

All API requests must be authenticated using Basic HTTP Auth. Authentication is performed using an Oktopost Account Id as the username and an API Key as the password. Both values can be found on the Profile Settings tab in your account: https://app.oktopost.com/user/me.

All API requests are subjected to the permissions set available for the user requesting the data. If the user does not have permissions to perform the action, the API response will be 403 (permission denied). If the user does not have access to a certain object, the API response will be 404 (not found).

Limiting Requests

The API has a global rate limit of 20,000 calls per day, per user. The limits are reset each day at midnight UTC. Burst rates allow for up to 60 calls per minute.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of an API call. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing or the API key was wrong), and codes in the 5xx range indicate an error on the Oktopost side.

HTTP Status Code Summary

20x OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
404 Not Found - The requested item does not exist.
50x Server errors - Something went wrong on our end.

Every set of results will contain the Result parameter which indicates if the response was successful or not. In case an error was captured, an Errors parameter will be returned as-well. For example:

{  
    "Result":false,
    "Errors":{  
        "API":{  
            "Error":"The page you are looking for was not found"
        }
    }
}

Pagination

All API endpoints that return lists of objects share a common structure. The following parameters can be used to iterate between pages and determine the number and order of the result set.

Param Default Description
_count 25 The number of items per page. Unless specified otherwise, options are: 25, 50 and 100
_page 0 The current page
_order created,0 The order of the result set. 0 means descending and 1 means ascending

Example Request

curl -i https://api.oktopost.com/v2/campaign?_count=100&_page=1&_order=created,0

Example Result

{
    "Result":true,
    "Items":[...],
    "Total":1024
}

Feedback and Knowledge Base