REST API

The Aptuitiv REST API enables developers to easily interact with your website via third-party applications or external data sources. Requests are made to the API using standard GET, POST, PUT, PATCH and DELETE commands and the API returns its results in JSON.

This is different from the internal data API that can be used to display content from one area of the website in another area.

Authentication

In order to access the API, you will need to provide an access token to authenticate with the API server. That token will be required for all API requests.

Authentication is done by passing a valid API token using the Authorization header.

Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9

The value for the "Authorization" header starts with Bearer followed by a space and then followed by the API token.

It is strongly recommended that you use https for all API requests to protect the authentication.

It is your responsibility to protect the API authentication.

You can generate an API token by going to Settings -> API in the administration.

Accept header required

All requests must include the "Accept" header. The only allowed value is "application/json".

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?limit=2'

User-Agent header required

All requests must include the User-Agent header.

Some tools such as Insomnia or curl on the command line will include a default User Agent. Other environments, like curl with PHP, do not set a default user agent. You would need to do this yourself.

Any valid user agent value can be used.

<?php
$url = "https://www.mysite.com/api/v1/account/accounts?limit=2";
$authToken = "MYAPIAUTHORIZATIONTOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("User-Agent: MyCustomUserAgent","Accept: application/json", "Content-Type: application/json", "Authorization: Bearer $authToken"));
$result = curl_exec($ch);
curl_close($ch)

Base URL

The base URL for all requests is /api/v1/.

HTTP verbs

Where possible the API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving a list of items or a single item.
POST	Used for creating items (e.g. adding a new calendar event). The POST request is also used for uploading an image or file.
PATCH	Used for partially updating an item. A PATCH request will accept one or more valid attributes for an item to update and only the passed attributes will be updated.
PUT	Used for replacing an item. This would completely edit the item. It's expected that all valid attributes are passed. If an attribute is left out then it's current value will be cleared when the item is saved.
DELETE	Used for deleting items.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

For example, when getting a list of events you can specify how many to return.

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?page=1&limit=5'

Default limit

If the limit parameter is not specified then the result will default to 20 items per set.

Common parameters

The following are some common parameters that you may use when making API requests.

Parameter	Description
attribute	One or more attributes to filter the results by. Essentially this will search for items that have values that match the passed value for each attribute. Data type: string The expected format for each attribute is layoutKey:value. Where "layoutKey" is the attribute layout key and "value" is the value to filter by. Multiple values can be separated with pipes layoutKey1:value1\|layoutKey2:value2. If multiple layout keys are specified then the filter will only return items that match all specified attributes and the specified values. Special characters are not allowed for the layout key. To use ':' or '\|' characters in values they must be prefixed with '\' (escape character). Examples Filter accounts where the first name equals "Bob". curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?attribute=firstName:Bob' Filter accounts where the first name equals "Bob" and the company name equals "Acme Inc". curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?attribute=firstName:Bob\|company=Acme+Inc'
instance	The instance key for the app. This is only needed if you have multiple instance of an app. For example, if you had two blog app instances. Data type: string Example curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?instance=company-calendar'
limit	The maximum number of items to retrieve. This is used when retrieving a list of items (like accounts or calendar events). It is usually used with the page parameter. If limit is not set then the default limit will be 20. Data type: integer Examples With the page parameter: curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?page=1&limit=5' Without the page parameter. Since the page parameter isn't set, it will return the first set of results. curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?limit=5'
page	The pagination page number to retrieve results for. This is used when retrieving a list of items (like accounts or calendar events). It is usually used with the limit parameter. Data type: integer Example curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?page=1&limit=5'
search	Searches the items by the query value. Data type: string Example Get calendar events and search for events that contain "Summer Festival". curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?search=Summer&20Festival'
sort	Sets how to sort the results. Data type: string The expected format for each sorting condition is [+/-]layoutKey where "+" means ascending, "-" means descending and "layoutKey" is the attribute layout key. Multiple values can be separated with pipes +layoutKey1\|-layoutKey2 Array syntax can be used for layout keys +layoutKey.subKey Other special characters are not allowed for the layout key. Examples Get 5 accounts and sort in descending order by the last name. curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?sort=+lastName&limit=5' Get 5 accounts and sort in descending order by the last name and then ascending order by the first name. curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?sort=+lastName\|+firstName&limit=5'

Responses

All API responses will be in JSON and HTTP status codes are used to indicate the type of response.

The contents of the response will depend on what type of request you made.

Getting a list of items

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?sort=+lastName&limit=5'

{
    data: [
       {
         ...item data here...
       },
       {
         ...item data here...
       },
    ],
    "pagination": {
        "currentPage": 1, 
        "perPage": 6,
        "count": 6,
        "totalPages": 312,
        "total": 1867,
        "links": {
            "next": "?page=2&limit=6&sort=-lastName"
        }
    },
    "totalItems": 1867
}

Retrieve a single item

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/94'

{
    "id": 132
    "title": "Event Title",
    ....more app item data here....
}

Adding an item

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events'

If the item was successfully created then a 201 HTTP status code is returned.

The data for the item that was just added is returned. Same as the response for retrieving a single item.

{
    "id": 132
    "title": "Event Title",
    ....more app item data here....
}

Editing an item

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events/10'

If the item was successfully edited then a 200 HTTP status code is returned.

The data for the item that was just edited is returned. Same as the response for retrieving a single item.

{
    "id": 132
    "title": "Event Title",
    ....more app item data here....
}

Deleting an item

curl -X DELETE --H 'Accept: application/json' --H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/1784'

No response is returned if the deletion is successful. A HTTP status code of 204 is returned.

Partially editing an item

curl -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events/10'

If the item was successfully edited then a 200 HTTP status code is returned.

The data for the item that was just edited is returned. Same response a retrieving a single item.

{
    "id": 132
    "title": "Event Title",
    ....more app item data here....
}

Uploading a file or image to an app item

curl -X POST -H 'Content-Type: multipart/form-data' -H 'Accept: text/html' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' {"type":"formData"} 'http://devhosted.aptuitiv.com/api/v1/calendar/upload?attribute=image'

Below is an example response from successfully uploading an image.

{
    "src": "/images/myimage.jpg",
    "fileName": "myimage.jpg",
    "fileExtension": "jpg",
    "type": "image",
    "typeName": "JPG Image",
    "alt": "",
    "height": "200",
    "width": "300"
}

Below is an example response from successfully uploading a PDF.

{
    "src": "/docs/myfile.pdf",
    "fileName": "myfile.pdf",
    "fileExtension": "pdf",
    "type": "pdf",
    "typeName": "PDF"
}

Errors

If there is an error in the request then the appropriate HTTP status code will be returned with the response headers. The response content will contain JSON similar to the following.

{
    "errors": [
        {
            "code": 401,
            "title": "Unauthorized",
            "detail": "API Key is not Valid"
        }
    ]
}

HTTP status codes

Successful API requests will have a 200 HTTP status code.

If there was an error, then a 4xx status code or a 500 status code will be returned.

Below is a list of status codes that could be returned.

Response Codes	Description
200	OK The request was successful and a valid response is returned.
201	Created The item was successfully created. This is returned when adding a new app item and it was successfully added.
204	No Content The request was successfully processed but no content is returned. This is the response code if an app item is successfully deleted.
400	Bad Request The request could not be processed due to an issue with how the request was made. Possible reasons for the error include: You may have specified an incorrect app instance key using the instance parameter. The item that you are trying to edit does not exist. The item you are trying to delete does not exist.
401	Unauthorized The request could not be authenticated. Either the API authentication key is missing or it's invalid.
404	Not Found Possible reasons for the error include: The requested URL is not a valid URL.
415	Unsupported Media Type Possible reasons for the error include: You left out the "Accept" header. The "Accept" header is required and must be set to "application/json". You are uploading a file but the "Content-Type" header is not set to "multipart/form-data".
422	Unprocessable Entity Possible reasons for the error include: You are trying to upload a file or image but the API request didn't include a file. You are trying to upload a file or image but you set the wrong attribute layout key for the file. You are trying to add or edit an item but the data is not valid.

Pagination

Requests that return multiple items will be paginated to 20 items by default. You can specify further pages with the page parameter. You can adjust the number of items returned by passing the limit parameter.

For example, getting the list of accounts without passing the page or limit parameters will return 20 results.

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts'

The response will also include pagination data and the total number of items that could be returned.

{
    data: [
       {
         ...item data here...
       },
       {
         ...item data here...
       },
    ],
    "pagination": {
        "currentPage": 1, 
        "perPage": 20,
        "count": 20,
        "totalPages": 94,
        "total": 1867,
        "links": {
            "next": "?page=2&limit=6&sort=-lastName"
        }
    },
    "totalItems": 1867
}

In the pagination data is a links object. This will contain the links to go to the previous or next page.

For example, if you passed the page parameter the pagination link data would include the previous and next URLs to retrieve the previous or next set of data.

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?page=3'

{
    data: [
       {
         ...item data here...
       },
       {
         ...item data here...
       },
    ],
    "pagination": {
        "currentPage": 3, 
        "perPage": 20,
        "count": 20,
        "totalPages": 94,
        "total": 1867,
        "links": {
            "previous": "?page=2&limit=20",
            "next": "?page=2&limit=6&sort=-lastName"
        }
    },
    "totalItems": 1867
}