Requests are made in REST style over HTTP. The request URL is made up of a base_url, dependent on the region; a version number, currently only v1; and an end point name.

curl -u "iamausername:iamapassword" "https://ca-eu.conversocial.com/api/1/annotation-types"

Response body

The response body is JSON by default, no other types are supported. HTTP states codes are used to differentiate successful requests from error conditions.
A successful request will return a HTTP 200 status code

http status: 200
{
    "annotations": [{
        "type_id": "564b5d709bd56c14074805ec",
        "value": "me@example.com",
        "created_date": "2016-05-50T01:10:00",
        "moderator_id": f17
    }],
    "paging": {
        "next_page": "https://ca-eu.conversocial.com/api/1/annotations?page_token=123fwdwfwedq312123"
    }
}

An unsuccessful request will return a HTTP status code relevent to the error and a message describing the error encountered.

http status: 404
{
    "status": "error",
    "message": "Customer with that ID does not exist",
}

Pagination

Queries that return more than the maximum number of results (50) will be paginated. A paging object is returned with a next_page property that should be called to return the next page of results. The special query string parameter page_token stores the start position of the next set of results. Modifying this value will result in uninteded consequences.
Page size can be changed with the page_size parameter.

curl "https://ca-eu.conversocial.com/api/1/annotation-types?page_size=10"

{
  "annotationtypes": [
        {
            "format": "short",
            "id": "564b5d709bd56c14074805ec",
            "is_active": true,
            "name": "Email"
        },
        {
            "format": "short",
            "id": "564b5d709bd56c14074805ed",
            "is_active": true,
            "name": "Phone number"
        },
        {
            "format": "long",
            "id": "564b5d709bd56c14074805ee",
            "is_active": true,
            "name": "Address"
        }
        {...},
        {...},
        {...},
        {...},
        {...},
        {...}
    ],
    "paging": {
        "next_page": "https://ca-eu.conversocial.com/api/1/annotation-types?page_size=10&page_token=1ond02mi3e9h20eimn29dn2e0rj203r"
    }
}

Date Formats

All dates and times stated in API responses are given in "Coordinated Universal Time", (UTC). These times can be converted to your local timezone after you receive the response. A time field will be formatted as follows 2013-11-18T11:20:24

Useful notes

Any requests that may edit properties of an object/model through an API call (e.g. POST, DELETE requests) will need a 'convoId' parameter in the request body. The reason for this is so that a History object takes this to record any actions taken by a moderator if an object/model has been altered through a request.