Request format v1.2

This page describes the request format defined by the Permission Marketing API. All endpoints will accept data conforming to this specification.

A request is returned in a success condition or an error condition.

Making a request

All requests to the Permission Marketing API:

  • Must be prefixed with the major version number of the release you are working with. For example, version 1.0.123 will be accessible via GET /v1/exampleEndpoint.
  • May be subject to rate limiting.

All requests must be requested over SSL (HTTPS) and present valid authorisation credentials.

Filtering by attribute

Filtering is optional, but may help you target specific resources quickly and efficiently. Not all attributes can be filtered, but a common attribute to sort by is id:

  • GET and HEAD requests support id being present or omitted.
  • POST requests will error if an id is present.
  • PUT requests may error if an id is omitted.
  • DELETE methods are usually filtered by the id attribute. However, some endpoints allow a collection to be deleted if filtered by other attributes.

The id attribute can be provided in your URI or in the query string, for example GET /exampleEndpoint/123/ or GET /exampleEndpoint/?id=123.

Pagination

In addition to filtered attributes, the request format can contain the following arguments. All of these arguments are optional:

Attribute Type Description Methods 
count
 int The number of resources to be returned which match the filter criteria. The response will return a count which is less than or equal to this value, depending on how many resources matched the filter criteria. The upper limit per request varies by endpoint, the default is "200". GET 
reverse
 bool If "true", requests a descending sort; otherwise items will be sorted in ascending order. Defaults to "false". GET 
sort
 string Specifies an attribute on which to sort. If omitted, resources will be sorted by id. GET 
start
 int/string/null The value of the first resource to fetch in a "page" - matched against the active sort attribute. This value doesn't have to specify an existing value; a partial value of "f" will return a page of results where the sort attribute is equal to or after "f". GET

A "null" value in start is treated as " " (empty string). All resources with a "null" value are omitted from the result set. Pagination is applied to the remaining resources (non-null) according to the supplied sort and reverse arguments.

Payload

A payload is a chunk of data contained within the request's body. Some methods require you to provide data in this format, others require a query string only. These two formats are explained below:

Format Method Description 
Query string
 GET, HEAD, DELETE Filters and sorting/pagination controls can be provided in a query string. The id attribute can also be provided in the URI. 
Request body
 POST, PUT Resource attributes must be presented within the 'request body' and can be encoded in a variety of ways (see below). The id attribute can be provided in the URI or in a query string.

Content-Type and encoding

In the PMAPI request payloads are decoded according to the specified Content-Type header. When issuing POST and PUT requests, please be sure to match your Content-Type header and the encoding of your payload. Please choose from the following supported types:

  • Content-Type: application/json;
  • Content-Type: application/x-www-form-urlencoded;
  • Content-Type: multipart/form-data;

A query string is used for GET, HEAD and DELETE. For this reason, encoding on these methods is not available.

Example requests

GET example

"GET /v1/exampleEndpoint/?foo=bar&sort=name&start=f&count=10"

// Query string:
{
    "foo"       : "bar",
    "sort"      : "name",
    "start"     : "f",
    "count"     : 10
}

// Request body:
{

}

HEAD example

# Using Token authentication

HEAD /v1/exampleEndpoint?id=123 HTTP/1.1
Host: api.sign-up.to
Accept: application/json
Authorization: SuTToken K/+zDxHsGi3H4xFxqIjtqo18ACW7bLnROKo9PJEv5YJEa7jou/J8qq0yY2Dg9/d/8aj7glze3yDqOeBynq3HI/ux/JU+shkK
Date: Thu, 25 Apr 2013 08:25:54 GMT
User-Agent: SUTAPI client v0.0.1


# Using CID/Hash authentication

HEAD /v1/exampleEndpoint?id=123 HTTP/1.1
Host: api.sign-up.to
Accept: application/json
Authorization: SuTHash signature="4de3399fc4ce479838395eacccc6842461ef5059"
Date: Thu, 25 Apr 2013 08:25:54 GMT
User-Agent: SUTAPI client v0.0.1
X-SuT-CID: 12345
X-SuT-UID: 4567
X-SuT-Nonce: bbabf11dce3a7a8511a20d93af7f2b5a04edd43f

POST example

"POST /v1/exampleEndpoint"

// Query string:
{

}

// Request body:
{
    "foo"         : "bar",
    "firstname"   : "John",
    "lastname"    : "Smith"
}

PUT example

"PUT /v1/exampleEndpoint/123/" or "PUT /v1/exampleEndpoint/?id=123"

// Query string:
{
    "id"          : 123
}

// Request body:
{
    "foo"         : "bar",
    "firstname"   : "John",
    "lastname"    : "Smith"
}

DELETE example

"DELETE /v1/exampleEndpoint/123/" or "DELETE /v1/exampleEndpoint/?id=123"

// Query string:
{
    "id"         : 123
}

// Request body:
{

}