Getting started with API integration

Welcome to the API for the middletwin platform. With the API you are able to execute various functions within your account on the middletwin platform.

Basics

All calls into the API need to be POST requests. Each API call needs to have the proper X header parameters for authentication (see below), and have a JSON formatted body (unless noted otherwise). All responses from our server will be in JSON format, we do not support XML or any other formats at this time. All JSON responses will have a success key with a boolean value indicating of the request was successful, and an errorMessage key that will have a string value if success is not true.

Authentication

To get started, you will need to obtain a set of API keys for the account that you want to use. Our API security requires a key pair to make API calls. One of the keys is a PUBLIC key, meaning we store it in our database and use it as a lookup for the account that you are accessing. The second key is a SECRET key. This key is not stored in our system, it is generated at the time the key is created, and is only visible at that time.

You will need this key pair before you can begin, and you will need to store them in a safe place.

The PUBLIC and SECRET key pair must be provided with every API call that you make as X headers in the request.

X-Apikey=<PUBLIC KEY>
X-SecretKey=<SECRET KEY>

If these keys are invalid or attempt to make a request to a resource that they do not have access to, you will receive a 401 response.

Requests

All requests are POST requests to the following URL:

https://app.middletwin.com/dart/core

The JSON body of the request has an ‘action’ attribute that dictates the action you would like to perform and any other parameters (required or optional) to support the request.

‘object types’ that list the actions.

Example
{
   "action":"get_all_members",
   "limit":"25",
   "offset":"0",
   "orderby":"lname",
   "nostatus":"true"
}

Responses

All responses will be in JSON and will have a success key with a boolean value and an errorMessage key with a string value.

Example
{
    "success":true,
    "errorMessage":"",
    "limit":"25",
    "offset":"0",
    "members":[...]
}

Actions

Actions are dependent on the permissions that your keys have access to. Key permissions are just like user permissions, and an API with a key pair is treated like a user with access to the account.

CRUD

Almost all resources in the middletwin platform have actions for basic CRUD functionality (Create, Read, Update, Delete). Most of the actions will be of the form create_<objecttype>, update_<objecttime>, etc… Create actions will almost always return with the id of the newly created object. Update and Delete will almost always require the id of the object you want to update or delete. In most cases, read operations (get) will respond with the entire object record. For some object types, the read operations that return multiple records are paginated.