NAV
API Documentation
shell

INTRODUCTION

Welcome to the Sprout API!

The Sprout API lets you tap into a Sprout accounts data and integrate your web, mobile or desktop based application.

Get up to speed with the Sprout API

REQUEST

The Sprout API is accessed from a dedicated Whitelabel URL which can be found when creating your App within Sprout. The format of the URL is either https://{whitelabel}.api.contacta.io, or https://api.{custom domain}.

Where

For consistency across the API documentation we will use {api url} in our examples.

All data is sent and received in JSON format, and all API requests require authentication.

HTTP Methods

Method Description
GET Retrieve resources
POST Create resources
PUT Partial update of resources
DELETE Delete resources

SSL/TLS

Make sure that all requests to the Sprout API are made over SSL/TLS (https:// not http://)

Query Parameters

Filtering

$ curl https://{api url}/contacts?searchType=and&email__contains=alex

Certain endpoints have filtering available to search for and limit the data returned. We've made it as simple as possible for you to use filters in the API as URL parameters.

Consult an endpoint's parameters description to check which properties are filterable for that endpoint.

The default behaviour of a filter is to perform a case-sensitive exact match against the value provided. A parameter used in filters can also be accompanied with a filter modifier to extend the type of filtering to be performed. A list of modifiers available is as follows.

Modifier Description Examples
lt Less than visits__lt=15
created__lt=2018-07-01T12:00:00Z
lte Less than or equal to visits__lte=15
created__lte=2018-07-01T12:00:00Z
gt Greater than visits__gt=15
created__gt=2018-07-01T12:00:00Z
gte Greater than or equal to visits__gte=15
created__gte=2018-07-01T12:00:00Z
eq Case-insensitive equal to firstName__eq=alex
neq Case-insensitive not equal to firstName__neq=alex
contains Case-insensitive contains firstName__contains=alex
ncontains Case-insensitive doesn't contain firstName__ncontains=alex
in In the given values (comma separated) visits__in=3,9,15
firstName__in=alex,phil,joe
nin Not in the given values (comma separated) visits__nin=3,9,15
firstName__nin=alex,phil,joe
startswith Case-insensitive starts with firstName__startswith=alex
nstartswith Case-insensitive doesn't start with firstName__nstartswith=alex
endswith Case-insensitive ends with firstName__endswith=alex
nendswith Case-insensitive doesn't end with firstName__nendswith=alex
range Within both values visits__range=15,20
created__range=2018-07-01T12:00:00Z,2018-07-02T12:00:00Z
isempty Is empty (null or blank) firstName__isempty=true
isnempty Is not empty (not null and not blank) firstName__isnempty=true

Pagination

$ curl https://{api url}/contacts?page=1&pageSize=10

Customer records in Sprout could be in the millions and you may not be interested in viewing the entire list at once. You can control the maximum number of records that are returned using the pageSize query parameter. To traverse through the entire dataset, use the page query parameter.

The default page size is 50 and maximum number of records that can be returned is 200 per request.

Sorting

$ curl https://{api url}/contacts?sortBy=email:asc

You can control in which order the results are returned by using the query parameter sortBy.

The sortBy parameter takes a field name to sort by.

The default sort order depends on the field being used. However you can explicitly specify the sort order by using the following modifiers after the field name.

Consult an endpoint's parameters description in order to check which properties are sortable for that endpoint.

Content Negotiation

Content-Type: application/json

Sprout API currently only supports JSON requests and responses. To ensure our API interprets your request correctly you will need to specify the Content-Type header and set it to a value of application/json.

Date and Time

2018-07-01T20:00:00+10:00
2018-07-01T12:00:00Z

Date and time formats can cause a lot of confusions and interoperability issues. To overcome this, we use the industry standard, ISO-8601. Dates are accepted with any timezone however they are converted, stored and returned in UTC.

Versioning

All API calls should be made with the Accept-Version header which guarantees that your call is using the correct API version. The version value is passed in as a numeric version of API 1.0.

RESPONSES

The Sprout API will always respond with JSON format, regardless of whether the request succeeds or fails.

Headers

Request Unique ID

Every response contains the X-Request-Id header which identifies a specific request. It has a random universally unique identifier (UUID) format: the same UUID as the one returned as the logRef in the error envelope.

Whenever you have a problem with a request, please get in touch with our support team to troubleshoot it and attach the unique identifier (UUID), which will help us to diagnose the problem.

Body

Successful Response

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "account": "00112233445566778899aabb",
                "accountName": "Acme",
                "firstName": "Joe",
                "surname": "Bloggs",
                "email": "noreply@example.com",
                "mobile": "",
                "dob": "2018-07-01T12:00:00.000Z",
                "gender": "m",
                "smsOptOut": false,
                "emailOptOut": false,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "lastContacted": "2018-07-01T12:00:00.000Z",
                "tags": [
                    "A tag",
                    "Another tag"
                ],
                "customFields": {
                    "Company": "Umbrella Corp",
                    "Country": "Australia"
                },
                "source": "CSV upload"
            },
            "meta": {
                "type": "contact"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 38707,
        "links": {
            "totalPage": 38707,
            "self": "/contacts?page=1&pageSize=1",
            "firstPage": "/contacts?page=1&pageSize=1",
            "nextPage": "/contacts?page=2&pageSize=1",
            "lastPage": "/contacts?page=38707&pageSize=1"
        }
    }
}

ID Format

Our ID format is a 24 character string consisting of characters 0 to 9 and a to f.

Date and Time

Date and time formats can cause a lot of confusion and interoperability issues. To overcome this, we use the industry standard, ISO 8601.

Envelope

Each API response is wrapped in a standard structure called the envelope, which holds the results of the API call, plus the metadata related to the request.

Name Description Type
items A collection of objects the payload carries collection
data An object the payload carries depends on endpoint
errors A collection of error objects collection
error The error object error
meta Payload's metadata information e.g. pagination, type etc. -

Meta

Metadata information is always returned in the response body within the unique meta field.

In a successful response, the meta object always holds the type attribute and pagination information, if the response is of type collection. The type can be one of the following values:

Name Example Description
collection - An array of objects
error - An error object
{resource name} contact Arbitrary resource type the payload carries

On an error response, the metadata object holds error-related information such as the httpStatus and logRef attributes.

Pagination

The pagination info is included in the meta attribute of the body’s envelope.

It is crucial to follow the links’ values instead of attempting to construct your own URLs.

Meta Attributes

Type Description
type Type of the response
count The number of items in a result
Type Description
self The URL of the current results
firstPage The URL of the first page of results
prevPage The URL of the immediate previous page of results
nextPage The URL of the next page of results
lastPage The URL of the last page of results

The links object will only include pertinent links. So for the first page of results, no firstPage or prevPage parameters will be included.

ERRORS

The Sprout API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx indicate an error with the information provided information in the request, codes in the 5xx range indicate a server-side error.

Body

Error Response

{
  "errors": [
    {
      "error": {
        "resource": "contact",
        "field": "",
        "code": 000000,
        "message": "",
        "details": ""
      },
      "meta": {
        "type": "error"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "httpStatus": 422,
    "logRef": ""
  }
}

The general format of an error's envelope includes two fields: errors and meta. They are described below in a separate subsection.

Error Attributes

The errors attribute is a JSON collection of objects that holds error information and related metadata, such as links to related documentation. Each error object can hold additional metadata in the meta object.

Error object represents either an invalid request error or resource error.

The error fields are described below:

Type Description
code The error code
message Human readable error description
details An optional detailed descriptive text
resource An optional resource name the error relates to, present only if the error represents a resource error
field An optional field name of the resource the error relates to, present only if the error represents a resource error

Meta Attributes

Name Description
httpStatus HTTP status code of the response plus HTTP response status message
logRef Unique ID of the request which is the same value as the X-Request-Id header

RATE LIMITING

To prevent API abuse, we have introduced a rate limit into Sprout API.

You can make up to 3,600 requests per hour. Every requests is considered on a per account basis. If you are consistently running into the current limits, please let us know.

If your limit reaches zero, subsequent requests will receive the 429 Too Many Requests

AUTHENTICATION

INTRODUCTION

All the requests to the Sprout API must be authenticated and must include a valid access token. The Sprout API utilises the industry-standard OAuth 2.0 protocol.

The greatest benefits of the OAuth protocol are its security and developer simplicity. Before we dive into the details of OAuth 2.0, we need to introduce some OAuth 2.0 nomenclature:

Application Registration

In order to make any call to the Sprout API, and to request your OAuth 2.0 access token, you need to register an application. Registered OAuth applications are assigned a unique Client ID (client_id) and a unique Client Secret (client_secret). Make sure to store the Client Secret securely.

Authentication Workflow and Endpoint

Sprout Authorisation allows you to use OAuth 2.0 via one of two flows:

Multi-User Application

The multi-user applications workflow is used by client applications where you need an access token for each user in your account. In this method of integration, the application acts on behalf of the resource owner who granted authorisation. Sprout supports multi-user applications only.

OAuth Endpoints

Sprout API provides the following OAuth 2.0 endpoints.

Endpoint Description
/oauth Authorisation endpoint
/oauth/token Token endpoint
/oauth/revoke Token revocation endpoint

Token Expiration

Each issued access token has a finite lifetime. The Sprout authorisation server, based on resource owner credentials, provides you with an access_token with the lifetime expires_in (in seconds) and refresh_token.

Requests with an expired access token will be rejected with a 401 status code. You need to use the refresh_token in order to obtain a new access_token.

SCOPES AND PERMISSIONS

Each access token is tagged with permission scopes. Scopes control whether the presented credentials are allowed to perform the request to the resource server. Permission scope is defined per account being accessed by an administration user, and cannot be requested during App authorization. The final set of permission scopes depends on the intersect of the App permissions and permissions of the user authorising the App.

Supported Scopes

Scope Description
accounts.view View account information
accounts.users.view View account users
accounts.child.view View sub-accounts
forms.view View forms and form submissions
fields.add Create contact field
fields.edit Update contact field
fields.delete Delete contact field
contacts.view View contacts
contacts.add Create contacts
contacts.edit Update contacts
contacts.delete Delete contacts
contacts.notes.view View contact notes
contacts.notes.add Create contact notes
contacts.notes.edit Update contact notes
contacts.notes.delete Delete contact notes
contacts.transactions.view View contact transactions
contacts.transactions.add Create contact transactions
contacts.transactions.edit Update contact transactions
contacts.transactions.delete Delete contact transactions
contacts.visits.view View contact visits
contacts.visits.add Create contact visits
contacts.visits.edit Update contact visits
contacts.visits.delete Delete contact visits

REQUESTS

Authorisation Code Workflow

Authorisation code workflow - Three Legged - is the most secure authentication workflow. This flow is optimised for web applications and requires your client application to handle redirection.

Your client application directs a resource owner to the Sprout Authorisation Server in order to grant authorisation. In that case, the client application doesn't need to store or even directly request any resource owner's credentials.

The flow includes the following steps: Authorisation Request and Token Request.

Authorisation Request

Request

$ curl https://{api url}/oauth?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}

Respoonse

HTTP/1.1 302 Found

Location: {redirect url}

In the first step, your client application directs a resource owner to the OAuth 2.0 /oauth authorisation endpoint and includes the following query parameters:

At this point, Sprout will ask the resource owner to log in (if necessary) and to authorise the application with the client_id. They can choose to deny the authorisation request as well. Afterwards, Sprout will redirect the resource owner back to the redirection URI provided earlier. The redirection URI will include the authorisation code within the code query parameter and the state value given in the previous request. The authorisation code is valid for 10 minutes.

Token Request

Request

$ curl -X POST https://{api url}/oauth/token \
     -d "client_id={client_id}" \
     -d "client_secret={client_secret}" \
     -d "grant_type=authorization_code" \
     -d "code={code}" \ 
     -d "redirect_uri={redirect_uri}"

Response

{
    "access_token":"00112233-4455-6677-8899-aabbccddeeff",
    "refresh_token":"00112233-4455-6677-8899-aabbccddeeff",
    "expires_in":432000,
    "scope":[
        "contacts.view",
        "contacts.edit",
        "contacts.add",
        "contacts.delete"
    ],
    "token_type":"Bearer"
}

The last step to follow is to request an access token using the authorisation code you received from the previous step.

In order to obtain an access token, perform a POST request to the /oauth/token token endpoint with the grant_type set to authorisation_code, and the redirect_uri set to the same value as in the previous step and the code set to the value of authorisation code you received from the last call. Remember that every request to the OAuth 2.0 token endpoint requires a client authentication.

If this request is successful, the Authorisation Server will authenticate the client, validate the authorisation code and the redirection URI, and will respond back with a JSON payload containing an access token, a refresh token, a token type set to bearer, an expiration time and list of permission scopes associated with the token.

Resource Access

$ curl -X GET https://{api url}/contacts \
      -H "Authorisation: Bearer {token}" \
      -H "Timestamp: {timestamp}"

To access protected resources, the resource owner needs to supply the access token in a format described in the industry-adopted standard OAuth 2.0 Bearer Token along with the current time stamp in Unix Time Stamp format. To authenticate to the API, use the standard Authorisation header using the Bearer authentication scheme to transmit the access token and the Timestamp header with the current Unix Time Stamp. The syntax for Authorisation and Timestamp header is shown below.

Requests with no Authorisation header will be rejected with 401 status code.

Refreshing Token

$ curl -X POST https://{api url}/oauth/token \
     -d "client_id={client_id}" \
     -d "client_secret={client_secret}" \
     -d "grant_type=refresh_token" \
     -d "refresh_token={refresh_token}"

Every access token issued has a finite lifetime as indicated by the expires_in field during token retrieval. The Sprout Authorisation Server provides you with an additional token called a refresh token, via refresh_token field.

Requests with an expired token will be rejected with a 401 status code. You need to use the refresh token credentials in order to obtain a new access token. Refresh tokens should not be sent to Resource Servers. They are intended to be used by Authorisation Server.

When your application receives a refresh token, it is important to store that refresh token securely for future use. If your client application loses the refresh token, you will have to prompt the resource owner for their credentials again.

In order to obtain a new access token a POST request to the /oauth/token token endpoint with grant_type set to refresh_token and refresh_token set to the value of the refresh token you obtained from the last call to the token endpoint. Remember that evert request to the OAuth 2.0 token endpoint requires client authentication.

Token Revocation

$ curl -X POST https://{api url}/oauth/revoke \
     -d "client_id={client_id}" \
     -d "client_secret={client_secret}" \
     -d "token={token}" \
     -d "token_type_hint={hint}"

Sprout API supports OAuth 2.0 Token revocation. You can perform a revocation requests of a single access token or a single refresh token and all its related access tokens.

To revoke a token, perform a POST request to the /oauth/revoke token revocation endpoint with token_type_hint set to either access_token to revoke the access token, or refresh_token to revoke the refresh token, and token set to value of the token you want to revoke.

The client_id also needs to be provided along with the client_secret if required by the App permissions.

ERRORS

This overview is available for information purpose and to highlight difference between Sprout API standard error response format and the OAuth authorisation error response format.

Response Format

The basic structure of an error response is a JSON object that holds error information at the highest object level. Error fields are described the table below.

{
  "error": "invalid_request",
  "error_description": "client_secret is invalid"
}
Name Description
error The error code
error_description An optional human readable error description

HTTP Error Codes

OAuth authorisation request can produce responses with the following HTTP status codes.

HTTP Status Code HTTP Status Message Meaning
200 OK Everything worked as expected
400 Bad Request There was something wrong with the request
401 Unauthorised Unauthorised client or token is being used
403 Forbidden Insufficient permissions to make the request
500 Internal Server Error Unexpected server error
503 Service Unavailable The API is currently unavailable

Authorisation Error Codes

Below is the summary of error codes and corresponding HTTP status codes for OAuth flow.

Requesting an Authorisation via /oauth

Error Code HTTP Status Code Meaning
invalid_request 400 The request is malformed, a required parameter is missing or a parameter has an invalid value.
unauthorised_client 401 The client is not authorised.
access_denied 401 The resource owner denied the request for authorisation.
unsupported_response_type 400 Unsupported response type.
invalid_scope 403 The scope is malformed or invalid.
server_error 500 Unexpected error.
temporarily_unavailable 503 The authorisation server is not able to handle the request.

Requesting an Access Token via /oauth/token

Error Code HTTP Status Code Meaning
invalid_request 400 The request is malformed, a required parameter is missing or a parameter has an invalid value.
invalid_client 401 Client authentication failed.
invalid_grant 400 Invalid authorisation grant, grant invalid, grant expired or grant revoked.
unauthorised_client 401 Client is not authorised to use the grant.
unsupported_grant_type 400 Authorisation grant is not supported by the Authorisation Server.
invalid_scope 403 The scope is malformed or invalid.

Revoking a Token via /oauth/revoke

Error Code HTTP Status Code Meaning
invalid_request 400 The request is malformed, a required parameter is missing or a parameter has an invalid value.
invalid_client 401 Client authentication failed.
invalid_grant 400 Invalid authorisation grant, grant invalid, grant expired or grant revoked.
unauthorised_client 401 Client is not authorised to use the grant.
unsupported_grant_type 400 Authorisation grant is not supported by the Authorisation Server.
invalid_scope 403 The scope is malformed or invalid.
unsupported_token_type 400 The Authorisation Server does not support revocation of the presented token type.

API ENDPOINTS

GET /accounts/:_id

Retrieve the details of a specific account

Request

$ curl -X GET 'https://{api url}/accounts/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Acme",
        "streetAddressLine1": "1 Main Street",
        "city": "Melbourne",
        "state": "VIC",
        "postcode": "3000",
        "country": "Australia",
        "timezone": "Australia/Melbourne",
        "status": "enabled",
        "accountOwners": [
            {
                "email": "noreply@example.com",
                "firstName": "Joe",
                "lastName": "Bloggs"
            }
        ],
        "users": [
            "00112233445566778899aabb",
            "00112233445566778899aabb"
        ],
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": {
            "_id": "00112233445566778899aabb",
            "email": "noreply@example.com"
        },
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "accountType": "parent",
        "parent": "00112233445566778899aabb",
        "parentPath": [
            "00112233445566778899aabb",
            "00112233445566778899aabb"
        ],
        "hasChild": false
    },
    "meta": {
        "type": "account"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the account

Response

Attribute Type Description
_id ID Unique identifier of the account
name String Name of the account
streetAddressLine1 String Address of the account
city String City of the account
state String State of the account
postcode String Postcode/zipcode of the account
country String Country of the account
timezone String Timezone of the account
status String The current status of the account (enabled, disabled or locked)
accountOwners.0.email String Email address of an account owner
accountOwners.0.firstName String First name of an account owner
accountOwners.0.lastName String Last name of an account owner
users Array of IDs Array of the accounts users
created ISO Date Date and time of when the account was created
createdBy._id ID ID of the user that created the account
createdBy.email String Email of the user that created the account
modified ISO Date Date and time of when the account was last modified
modifiedBy ID ID of the user that last modified the account
accountType String Indicator if the account is parent or child
parent ID ID of this accounts parent
parentPath Array of IDs The ordered list of ancestral accounts from the main account down to the current account
hasChild Boolean Flag to indicate if this account has sub accounts

GET /accounts/:_id/children

Retrieve a list of sub accounts belonging to a specific account

Request

$ curl -X GET 'https://{api url}/accounts/{id}/children' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "name": "Acme",
                "streetAddressLine1": "1 Main Street",
                "city": "Melbourne",
                "state": "VIC",
                "postcode": "3000",
                "country": "Australia",
                "timezone": "Australia/Melbourne",
                "status": "enabled",
                "accountOwners": [
                    {
                        "email": "noreply@example.com",
                        "firstName": "Joe",
                        "lastName": "Bloggs"
                    }
                ],
                "users": [
                    "00112233445566778899aabb",
                    "00112233445566778899aabb"
                ],
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": {
                    "_id": "00112233445566778899aabb",
                    "email": "noreply@example.com"
                },
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "accountType": "child",
                "parent": "00112233445566778899aabb",
                "parentPath": [
                    "00112233445566778899aabb",
                    "00112233445566778899aabb"
                ],
                "hasChild": false
            },
            "meta": {
                "type": "account"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/accounts/00112233445566778899aabb/children"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the account

Response

Attribute Type Description
_id ID Unique identifier of the account
name String Name of the account
streetAddressLine1 String Address of the account
city String City of the account
state String State of the account
postcode String Postcode/zipcode of the account
country String Country of the account
timezone String Timezone of the account
status String The current status of the account (enabled, disabled or locked)
accountOwners.0.email String Email address of an account owner
accountOwners.0.firstName String First name of an account owner
accountOwners.0.lastName String Last name of an account owner
users Array of IDs Array of the accounts users
created ISO Date Date and time of when the account was created
createdBy._id ID ID of the user that created the account
createdBy.email String Email of the user that created the account
modified ISO Date Date and time of when the account was last modified
modifiedBy ID ID of the user that last modified the account
accountType String Indicator if the account is parent or child
parent ID ID of this accounts parent
parentPath Array of IDs The ordered list of ancestral accounts from the main account down to the current account
hasChild Boolean Flag to indicate if this account has sub accounts

GET /accounts/:_id/children/:child_id

Retrieve the details of a specific sub-account

Request

$ curl -X GET 'https://{api url}/accounts/{id}/children/{child_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Acme",
        "streetAddressLine1": "1 Main Street",
        "city": "Melbourne",
        "state": "VIC",
        "postcode": "3000",
        "country": "Australia",
        "timezone": "Australia/Melbourne",
        "status": "enabled",
        "accountOwners": [
            {
                "email": "noreply@example.com",
                "firstName": "Joe",
                "lastName": "Bloggs"
            }
        ],
        "users": [
            "00112233445566778899aabb",
            "00112233445566778899aabb"
        ],
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": {
            "_id": "00112233445566778899aabb",
            "email": "noreply@example.com"
        },
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "accountType": "child",
        "parent": "00112233445566778899aabb",
        "parentPath": [
            "00112233445566778899aabb",
            "00112233445566778899aabb"
        ],
        "hasChild": false
    },
    "meta": {
        "type": "account"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the account
client_id ID Unique identifier of the sub-account

Response

Attribute Type Description
_id ID Unique identifier of the account
name String Name of the account
streetAddressLine1 String Address of the account
city String City of the account
state String State of the account
postcode String Postcode/zipcode of the account
country String Country of the account
timezone String Timezone of the account
status String The current status of the account (enabled, disabled or locked)
accountOwners.0.email String Email address of an account owner
accountOwners.0.firstName String First name of an account owner
accountOwners.0.lastName String Last name of an account owner
users Array of IDs Array of the accounts users
created ISO Date Date and time of when the account was created
createdBy._id ID ID of the user that created the account
createdBy.email String Email of the user that created the account
modified ISO Date Date and time of when the account was last modified
modifiedBy ID ID of the user that last modified the account
accountType String Indicator if the account is parent or child
parent ID ID of this accounts parent
parentPath Array of IDs The ordered list of ancestral accounts from the main account down to the current account
hasChild Boolean Flag to indicate if this account has sub accounts

GET /accounts/:_id/users

Retrieve a list of account users

Request

$ curl -X GET 'https://{api url}/accounts/{id}/users' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "email": "noreply@example.com",
                "firstName": "Joe",
                "lastName": "Bloggs",
                "fullName": "Joe Bloggs",
                "phone": "",
                "avatar": "",
                "country": "Australia",
                "status": "enabled",
                "lastLogin": "2018-07-01T12:00:00.000Z",
                "statusOnAccount": "enabled",
                "roles": [
                    "Account Owner"
                ]
            },
            "meta": {
                "type": "user"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/accounts/00112233445566778899aabb/users"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the account

Response

Attribute Type Description
_id ID Unique identifier of the user
email String Email address of the user
firstName String First name of the user
lastName String Last name of the user
fullName String Full name of the user
phone String Mobile / cell phone of the user
avatar String URL of the profile image of the user
country String User's country
status String The users status on the platform (enabled or disabled)
lastLogin ISO Date The last login of this user
statusOnAccount String The users status on this account (enabled or disabled)
roles Array of Strings The roles assigned to this user within the account

GET /accounts/:_id/users/:user_id

Retrieve the details of a specific user within an account

Request

$ curl -X GET 'https://{api url}/accounts/{id}/users/{user_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "email": "noreply@example.com",
        "firstName": "Joe",
        "lastName": "Bloggs",
        "fullName": "Joe Bloggs",
        "phone": "",
        "avatar": "",
        "country": "Australia",
        "status": "enabled",
        "lastLogin": "2018-07-01T12:00:00.000Z",
        "statusOnAccount": "enabled",
        "roles": [
            "Account Owner"
        ]
    },
    "meta": {
        "type": "user"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the account

Response

Attribute Type Description
_id ID Unique identifier of the user
email String Email address of the user
firstName String First name of the user
lastName String Last name of the user
fullName String Full name of the user
phone String Mobile / cell phone of the user
avatar String URL of the profile image of the user
country String User's country
status String The users status on the platform (enabled or disabled)
lastLogin ISO Date The last login of this user
statusOnAccount String The users status on this account (enabled or disabled)
roles Array of Strings The roles assigned to this user within the account

GET /contacts

Retrieve a list of contacts stored for a specific account

Request

$ curl -X GET 'https://{api url}/contacts' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "account": "00112233445566778899aabb",
                "accountName": "Acme",
                "firstName": "Joe",
                "surname": "Bloggs",
                "email": "noreply@example.com",
                "mobile": "",
                "dob": "2018-07-01T12:00:00.000Z",
                "gender": "Male",
                "smsOptOut": false,
                "emailOptOut": false,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "tags": [
                    "A tag",
                    "Another tag"
                ],
                "customFields": {
                    "company": "Umbrella Corp",
                    "country": "Australia"
                },
                "source": "CSV upload"
            },
               "meta": {
                "type": "contact"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/contacts"
        }
    }
}

Response

Attribute Type Description
_id ID Unique identifier of the contact
account ID Reference to the account the contact belongs to
accountName String Account name the contact belongs to
firstName String Contact's first name
surname String Contact's surname
email String Contact's email
mobile String Contact's mobile
dob ISO Date Contact's date of birth
gender String Contact's gender
smsOptOut Boolean Whether the contact has been opted out of SMS marketing or not
emailOptOut Boolean Whether the contact has been opted out of email marketing or not
deleted Boolean Whether the contact has been deleted or not
created ISO Date Date and time of when the contact was created
createdBy ID ID of the user that created the contact
modified ISO Date Date and time of when the contact was last modified
modifiedBy ID ID of the user that last modified the contact
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details
source String How the contact was created in the account

POST /contacts

Create/update a contact for a specific account. This endpoint will update a contact if a duplicate contact exists or create a new contact if one isn't found.

Duplicate contacts are determined by an email or mobile. There should only be at most one unique email or mobile per account. As a result a request will fail if one existing contact has an email and another existing contact has a mobile and the request has both the email and mobile provided, since this will create a duplicate contact.

Request

## Single contact request

$ curl -X POST 'https://{api url}/contacts' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "firstName": "Joe",
                  "surname": "Bloggs",
                  "email": "noreply@example.com",
                  "mobile": "",
                  "dob": "2018-07-01T12:00:00.000Z",
                  "gender": "m",
                  "smsOptOut": false,
                  "emailOptOut": false,
                  "deleted": false,
                  "tags": [
                      "A tag",
                      "Another tag"
                  ],
                  "customFields": {
                      "Company": "Umbrella Corp",
                      "Country": "Australia"
                  }
              }
          }
      '

## Multi contact request

$ curl -X POST 'https://{api url}/contacts' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "items": [
                  {
                      "data": {
                          "firstName": "Joe",
                          "surname": "Bloggs",
                          "email": "noreply@example.com",
                          "mobile": "",
                          "dob": "2018-07-01T12:00:00.000Z",
                          "gender": "m",
                          "smsOptOut": false,
                          "emailOptOut": false,
                          "deleted": false,
                          "tags": [
                              "A tag",
                              "Another tag"
                          ],
                          "customFields": {
                              "Company": "Umbrella Corp",
                              "Country": "Australia"
                          }
                      }
                  }
              ]
          }
      '

Response

## Single contact request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "firstName": "Joe",
        "surname": "Bloggs",
        "email": "noreply@example.com",
        "mobile": "",
        "dob": "2018-07-01T12:00:00.000Z",
        "gender": "m",
        "smsOptOut": false,
        "emailOptOut": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "tags": [
            "A tag",
            "Another tag"
        ],
        "customFields": {
            "Company": "Umbrella Corp",
            "Country": "Australia"
        },
        "source": "App",
        "updated": true
    },
    "meta": {
        "type": "contact"
    }
}

## Multi contact request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "account": "00112233445566778899aabb",
                "firstName": "Joe",
                "surname": "Bloggs",
                "email": "noreply@example.com",
                "mobile": "",
                "dob": "2018-07-01T12:00:00.000Z",
                "gender": "m",
                "smsOptOut": false,
                "emailOptOut": false,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "tags": [
                    "A tag",
                    "Another tag"
                ],
                "customFields": {
                    "Company": "Umbrella Corp",
                    "Country": "Australia"
                },
                "source": "App",
                "updated": true
            },
            "meta": {
                "type": "contact"
            },
            "error": {
                "resource": "contact",
                "field": "",
                "code": 000000,
                "message": "",
                "details": ""
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 0,
        "updated": 1,
        "failed": 0
    }
}

Body Parameters

Attribute Type Description
email String Contact's email
mobile String Contact's mobile
firstName String Contact's first name
surname String Contact's surname
dob ISO Date Contact's date of birth
gender String Contact's gender (m or f)
smsOptOut Boolean Whether the contact should be opted out of SMS marketing or not
emailOptOut Boolean Whether the contact should be opted out of email marketing or not
deleted Boolean Whether the contact should be flagged as deleted
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts. Any tags that don't exist in the account will be created as part of the request
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details

Fields must pre-exist for data to be captured. Any fields in the data that don't exist will be ignored

Response

Attribute Type Description
_id ID Unique identifier of the contact
account ID Reference to the account the contact belongs to
firstName String Contact's first name
surname String Contact's surname
email String Contact's email
mobile String Contact's mobile
dob ISO Date Contact's date of birth
gender String Contact's gender
smsOptOut Boolean Whether the contact has been opted out of SMS marketing or not
emailOptOut Boolean Whether the contact has been opted out of email marketing or not
deleted Boolean Whether the contact has been deleted or not
created ISO Date Date and time of when the contact was created
createdBy ID ID of the user that created the contact
modified ISO Date Date and time of when the contact was last modified
modifiedBy ID ID of the user that last modified the contact
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details
source String How the contact was created in the account
updated Boolean Flag to indicate if the request added or updated a contact in the account
error Object A description of the error that occurred for a contact that failed to add/update during a multi contact request

GET /contacts/:_id

Retrieve a specific contact from a specific account.

Request

$ curl -X GET 'https://{api url}/contacts/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "accountName": "Acme",
        "firstName": "Joe",
        "surname": "Bloggs",
        "email": "noreply@example.com",
        "mobile": "",
        "dob": "2018-07-01T12:00:00.000Z",
        "gender": "m",
        "smsOptOut": false,
        "emailOptOut": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "tags": [
            "A tag",
            "Another tag"
        ],
        "customFields": {
            "Company": "Umbrella Corp",
            "Country": "Australia"
        },
        "source": "App"
    },
    "meta": {
        "type": "contact"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Response

Attribute Type Description
_id ID Unique identifier of the contact
account ID Reference to the account the contact belongs to
accountName String Account name the contact belongs to
firstName String Contact's first name
surname String Contact's surname
email String Contact's email
mobile String Contact's mobile
dob ISO Date Contact's date of birth
gender String Contact's gender
smsOptOut Boolean Whether the contact has been opted out of SMS marketing or not
emailOptOut Boolean Whether the contact has been opted out of email marketing or not
deleted Boolean Whether the contact has been deleted or not
created ISO Date Date and time of when the contact was created
createdBy ID ID of the user that created the contact
modified ISO Date Date and time of when the contact was last modified
modifiedBy ID ID of the user that last modified the contact
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details
source String How the contact was created in the account

PUT /contacts/:_id

Update a contact for a specific account

Request

$ curl -X PUT 'https://{api url}/contacts/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "firstName": "Joe",
                  "surname": "Bloggs",
                  "email": "noreply@example.com",
                  "mobile": "",
                  "dob": "2018-07-01T12:00:00.000Z",
                  "gender": "m",
                  "smsOptOut": false,
                  "emailOptOut": false,
                  "tags": [
                      "A tag",
                      "Another tag"
                  ],
                  "customFields": {
                      "Company": "Umbrella Corp",
                      "Country": "Australia"
                  }
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "firstName": "Joe",
        "surname": "Bloggs",
        "email": "noreply@example.com",
        "mobile": "",
        "dob": "2018-07-01T12:00:00.000Z",
        "gender": "m",
        "smsOptOut": false,
        "emailOptOut": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "tags": [
            "A tag",
            "Another tag"
        ],
        "customFields": {
            "Company": "Umbrella Corp",
            "Country": "Australia"
        },
        "source": "App"
    },
    "meta": {
        "type": "contact"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
email String Contact's email
mobile String Contact's mobile
firstName String Contact's first name
surname String Contact's surname
dob ISO Date Contact's date of birth
gender String Contact's gender (m or f)
smsOptOut Boolean Whether the contact should be opted out of SMS marketing or not
emailOptOut Boolean Whether the contact should be opted out of email marketing or not
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts. Any tags that don't exist in the account will be created as part of the request
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details

Fields must pre-exist for data to be captured. Any fields in the data that don't exist will be ignored

Response

Attribute Type Description
_id ID Unique identifier of the contact
account ID Reference to the account the contact belongs to
accountName String Account name the contact belongs to
firstName String Contact's first name
surname String Contact's surname
email String Contact's email
mobile String Contact's mobile
dob ISO Date Contact's date of birth
gender String Contact's gender
smsOptOut Boolean Whether the contact has been opted out of SMS marketing or not
emailOptOut Boolean Whether the contact has been opted out of email marketing or not
deleted Boolean Whether the contact has been deleted or not
created ISO Date Date and time of when the contact was created
createdBy ID ID of the user that created the contact
modified ISO Date Date and time of when the contact was last modified
modifiedBy ID ID of the user that last modified the contact
tags Array of Strings Tags assigned to the contact to help with segmenting the contacts
customFields Object A key / value object of extra contact fields being captured by the account representing the field and value captured. Refer to the /fields endpoints for details
source String How the contact was created in the account

DELETE /contacts/:_id

Delete a contact from an account

Request

$ curl -X DELETE 'https://{api url}/contacts/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

GET /contacts/:_id/notes

Retrieve notes for a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/notes' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "noteDate": "2018-07-01T12:00:00.000Z",
                "note": "This is my note",
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "deleted": false
            },
            "meta": {
                "type": "notes"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/contacts/00112233445566778899aabb/notes"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Response

Attribute Type Description
_id ID Unique identifier of the note
contact ID Reference to the contact this note belongs to
noteDate ISO Date The date of the note
note String The note message
created ISO Date The date and time the note was created
createdBy ID The ID of the user that created the note
modified ISO Date The date and time the note was last modified
modifiedBy ID The ID of the user that last modified the note
deleted Boolean Whether this note has been deleted or not

POST /contacts/:_id/notes

Create a new note for a specific contact

Request

## Single note request

$ curl -X POST 'https://{api url}/contacts/{id}/notes' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "note": "This is my note",
                  "noteDate": "2018-07-01T12:00:00.000Z"
              }
          }
      '

## Multi note request

$ curl -X POST 'https://{api url}/contacts/{id}/notes' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "items": [
                  {
                      "data": {
                          "note": "This is my note",
                          "noteDate": "2018-07-01T12:00:00.000Z"
                      }
                  }
              ]
          }
      '

Response

## Single note request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "noteDate": "2018-07-01T12:00:00.000Z",
        "note": "This is my note",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "deleted": false
    },
    "meta": {
        "type": "notes"
    }
}

## Multi note request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "noteDate": "2018-07-01T12:00:00.000Z",
                "note": "This is my note",
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "deleted": false
            },
            "meta": {
                "type": "notes"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "failed": 0
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
note String The note message to add to the contact
noteDate ISO Date (Optional) The date to assign to the note. If omitted the current date will be used.

Response

Attribute Type Description
_id ID Unique identifier of the note
contact ID Reference to the contact this note belongs to
noteDate ISO Date The date of the note
note String The note message
created ISO Date The date and time the note was created
createdBy ID The ID of the user that created the note
modified ISO Date The date and time the note was last modified
modifiedBy ID The ID of the user that last modified the note
deleted Boolean Whether this note has been deleted or not

GET /contacts/:_id/notes/:note_id

Retrieve a specific note for a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/notes/{note_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "noteDate": "2018-07-01T12:00:00.000Z",
        "note": "This is my note",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "deleted": false
    },
    "meta": {
        "type": "notes"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
note_id ID Unique identifier of the note

Response

Attribute Type Description
_id ID Unique identifier of the note
contact ID Reference to the contact this note belongs to
noteDate ISO Date The date of the note
note String The note message
created ISO Date The date and time the note was created
createdBy ID The ID of the user that created the note
modified ISO Date The date and time the note was last modified
modifiedBy ID The ID of the user that last modified the note
deleted Boolean Whether this note has been deleted or not

PUT /contacts/:_id/notes/:note_id

Update an existing note for a specific contact

Request

$ curl -X PUT 'https://{api url}/contacts/{id}/notes/{note_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "note": "This is my note",
                  "noteDate": "2018-07-01T12:00:00.000Z"
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "noteDate": "2018-07-01T12:00:00.000Z",
        "note": "This is my note",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "deleted": false
    },
    "meta": {
        "type": "notes"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
note_id ID Unique identifier of the note

Body Parameters

Attribute Type Description
note String The note message to add to the contact
noteDate ISO Date The date to assign to the note

Response

Attribute Type Description
_id ID Unique identifier of the note
contact ID Reference to the contact this note belongs to
noteDate ISO Date The date of the note
note String The note message
created ISO Date The date and time the note was created
createdBy ID The ID of the user that created the note
modified ISO Date The date and time the note was last modified
modifiedBy ID The ID of the user that last modified the note
deleted Boolean Whether this note has been deleted or not

DELETE /contacts/:_id/notes/:note_id

Delete a note from a specific contact

Request

$ curl -X DELETE 'https://{api url}/contacts/{id}/notes/{note_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
note_id ID Unique identifier of the note

POST /contacts/:_id/tags

Add new contact tag(s) for a specific contact

Request

## Single tag request

$ curl -X POST 'https://{api url}/contacts/{_id}/tags' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                "value": ["tag1"]
              }
          }
      '

## Multi tag request

$ curl -X POST 'https://{api url}/contacts/{_id}/tags' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                "value": ["tag1", "tag2", "tag3"]
              }
          }
      '

Response

## Single tag request

HTTP/1.1 200

{
    "data": [
        "existingTag1",
        "tag1",
    ],
    "meta": {
        "type": "contact"
    }
}

## Multi tag request

HTTP/1.1 200

{
    "data": [
        "existingTag1",
        "tag1",
        "tag2",
        "tag3",
    ],
    "meta": {
        "type": "contact"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
tags Array of String The array of tag(s) to add to the contact

Response

Attribute Type Description
tags Array of String The array of tag(s) that is currently attached to the contact

DELETE /contacts/:_id/tags

Delete tag(s) from a specific contact

Request

## Single tag request

$ curl -X POST 'https://{api url}/contacts/{_id}/tags' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                "value": ["tag1"]
              }
          }
      '

## Multi tag request

$ curl -X DELETE 'https://{api url}/contacts/{_id}/tags' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                "value": ["tag1", "tag2", "tag3"]
              }
          }
      '

Response

## Single tag request

HTTP/1.1 200

{
    "data": [
        "existingTag1",
    ],
    "meta": {
        "type": "contact"
    }
}

## Multi tag request

HTTP/1.1 200

{
    "data": [
        "existingTag1",
        "existingTag2",
    ],
    "meta": {
        "type": "contact"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
tags Array of String The array of tag(s) to add to the contact

Response

Attribute Type Description
tags Array of String The array of tag(s) that is currently attached to the contact

GET /contacts/:_id/transactions

Retrieve a list of transactions for a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/transactions' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "visit": "00112233445566778899aabb",
                "location": "Main St",
                "reference": "INV0001",
                "transactedAt": "2018-07-01T12:00:00.000Z",
                "items": [
                    {
                        "_id": "00112233445566778899aabb",
                        "code": "",
                        "lineNo": 1,
                        "description": "Anvil",
                        "quantity": 1.0,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 100.00
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 10.00
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 110.00
                        },
                        "subItems": [
                            {
                                "code": "",
                                "lineNo": 1,
                                "description": "Extra Heavy",
                                "quantity": 1.0,
                                "unitPrice": {
                                    "currency": "AUD",
                                    "amount": 10.00
                                },
                                "tax": {
                                    "currency": "AUD",
                                    "amount": 1.00
                                },
                                "total": {
                                    "currency": "AUD",
                                    "amount": 11.00
                                }
                            }
                        ]
                    }
                ]
            },
            "meta": {
                "type": "transaction"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/contacts/00112233445566778899aabb/transactions"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Response

Attribute Type Description
_id ID Unique identifier of the transaction
contact ID Reference to the contact this transaction belongs to
visit ID Reference to the visit this transaction is related to
location String The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0._id ID Unique identifier of the item
items.0.code String The product code assigned to this item
items.0.lineNo Integer The display order of this item
items.0.description String The product description given to this item
items.0.category String The product category assigned to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.tax.amount Double The tax charged for this item
items.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String The product code assigned to this sub item
items.0.subItems.0.lineNo Integer The display order of this sub item
items.0.subItems.0.description String The product description given to this item
items.0.subItems.0.category String The product category assigned to this item
items.0.subItems.0.quantity Double The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.subItems.0.unitPrice.amount Double The price of the sub item
items.0.subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.subItems.0.tax.amount Double The tax charged for this sub item
items.0.subItems.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.subItems.0.total.amount Double The total charged for this sub item

POST /contacts/:_id/transactions

Create transactions for a specific contact

Request

## Single transaction request

$ curl -X POST 'https://{api url}/contacts/{id}/transactions' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "visit": "00112233445566778899aabb",
                  "location": "Main St",
                  "reference": "INV0001",
                  "transactedAt": "2018-07-01T12:00:00.000Z",
                  "items": [
                      {
                          "code": "",
                          "lineNo": 1,
                          "description": "Anvil",
                          "category": "Tools", 
                          "quantity": 1.0,
                          "unitPrice": {
                              "currency": "AUD",
                              "amount": 100.00
                          },
                          "tax": {
                              "currency": "AUD",
                              "amount": 10.00
                          },
                          "total": {
                              "currency": "AUD",
                              "amount": 110.00
                          },
                          "subItems": [
                              {
                                  "code": "",
                                  "lineNo": 1,
                                  "description": "Extra Heavy",
                                  "category": "Tools",
                                  "quantity": 1.0,
                                  "unitPrice": {
                                      "currency": "AUD",
                                      "amount": 10.00
                                  },
                                  "tax": {
                                      "currency": "AUD",
                                      "amount": 1.00
                                  },
                                  "total": {
                                      "currency": "AUD",
                                      "amount": 11.00
                                  }
                              }
                          ]
                      }
                  ]
              }
          }
      '

## Multi transaction request

$ curl -X POST 'https://{api url}/contacts/{id}/transactions' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "items": [
                  {
                      "data": {
                          "visit": "00112233445566778899aabb",
                          "location": "Main St",
                          "reference": "INV0001",
                          "transactedAt": "2018-07-01T12:00:00.000Z",
                          "items": [
                              {
                                  "code": "",
                                  "lineNo": 1,
                                  "description": "Anvil",
                                  "category": "Tools",
                                  "quantity": 1.0,
                                  "unitPrice": {
                                      "currency": "AUD",
                                      "amount": 100.00
                                  },
                                  "tax": {
                                      "currency": "AUD",
                                      "amount": 10.00
                                  },
                                  "total": {
                                      "currency": "AUD",
                                      "amount": 110.00
                                  },
                                  "subItems": [
                                      {
                                          "code": "",
                                          "lineNo": 1,
                                          "description": "Extra Heavy",
                                          "category": "Tools",
                                          "quantity": 1.0,
                                          "unitPrice": {
                                              "currency": "AUD",
                                              "amount": 10.00
                                          },
                                          "tax": {
                                              "currency": "AUD",
                                              "amount": 1.00
                                          },
                                          "total": {
                                              "currency": "AUD",
                                              "amount": 11.00
                                          }
                                      }
                                  ]
                              }
                          ]
                      }
                  }
              ]
          }
      '

Response

## Single transaction request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "visit": "00112233445566778899aabb",
        "location": "Main St",
        "reference": "INV0001",
        "transactedAt": "2018-07-01T12:00:00.000Z",
        "items": [
            {
                "_id": "00112233445566778899aabb",
                "code": "",
                "lineNo": 1,
                "description": "Anvil",
                "category": "Tools", 
                "quantity": 1.0,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 100.00
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 10.00
                },
                "total": {
                    "currency": "AUD",
                    "amount": 110.00
                },
                "subItems": [
                    {
                        "code": "",
                        "lineNo": 1,
                        "description": "Extra Heavy",
                        "category": "Tools", 
                        "quantity": 1.0,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 10.00
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 1.00
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 11.00
                        }
                    }
                ]
            }
        ]
    },
    "meta": {
        "type": "transaction"
    }
}

## Multi transaction request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "visit": "00112233445566778899aabb",
                "location": "Main St",
                "reference": "INV0001",
                "transactedAt": "2018-07-01T12:00:00.000Z",
                "items": [
                    {
                        "_id": "00112233445566778899aabb",
                        "code": "",
                        "lineNo": 1,
                        "description": "Anvil",
                        "category": "Tools", 
                        "quantity": 1,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 100
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 10
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 110
                        },
                        "subItems": [
                            {
                                "code": "456",
                                "lineNo": 1,
                                "description": "Extra Heavy",
                                "category": "Tools", 
                                "quantity": 1,
                                "unitPrice": {
                                    "currency": "AUD",
                                    "amount": 10
                                },
                                "tax": {
                                    "currency": "AUD",
                                    "amount": 1
                                },
                                "total": {
                                    "currency": "AUD",
                                    "amount": 11
                                }
                            }
                        ]
                    }
                ]
            },
            "meta": {
                "type": "transaction"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "failed": 0
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
visit ID (Optional) Reference to the visit this transaction is related to
location String (Optional) The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0.code String The product code assigned to this item
items.0.lineNo Integer (Optional) The display order of this item
items.0.description String The product description given to this item
items.0.category String The product category assigned to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String (Optional) The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String (Optional) The taxes currency (USD, AUD, GBP). Currency set to account if not provided
items.0.tax.amount Double (Optional) The tax charged for this item
items.0.total.currency String (Optional) The totals currency (USD, AUD, GBP). Currency set to account if not provided
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String (Optional) The product code assigned to this sub item
items.0.subItems.0.lineNo Integer (Optional) The display order of this sub item
items.0.subItems.0.description String (Optional) The product description given to this item
items.0.subItems.0.category String The product category assigned to this item
items.0.subItems.0.quantity Double (Optional) The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String (Optional) The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.unitPrice.amount Double (Optional) The price of the sub item
items.0.subItems.0.tax.currency String (Optional) The taxes currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.tax.amount Double (Optional) The tax charged for this sub item
items.0.subItems.0.total.currency String (Optional) The totals currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.total.amount Double (Optional) The total charged for this sub item

Response

Attribute Type Description
_id ID Unique identifier of the transaction
contact ID Reference to the contact this transaction belongs to
visit ID Reference to the visit this transaction is related to
location String The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0._id ID Unique identifier of the item
items.0.code String The product code assigned to this item
items.0.lineNo Integer The display order of this item
items.0.description String The product description given to this item
items.0.category String The product category assigned to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.tax.amount Double The tax charged for this item
items.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String The product code assigned to this sub item
items.0.subItems.0.lineNo Integer The display order of this sub item
items.0.subItems.0.description String The product description given to this item
items.0.subItems.0.category String The product category assigned to this item
items.0.subItems.0.quantity Double The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.subItems.0.unitPrice.amount Double The price of the sub item
items.0.subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.subItems.0.tax.amount Double The tax charged for this sub item
items.0.subItems.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.subItems.0.total.amount Double The total charged for this sub item

GET /contacts/:_id/transactions/:transaction_id

Retrieve a specific transaction from a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/transactions/{transaction_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "visit": "00112233445566778899aabb",
        "location": "Main St",
        "reference": "INV0001",
        "transactedAt": "2018-07-01T12:00:00.000Z",
        "items": [
            {
                "_id": "00112233445566778899aabb",
                "code": "",
                "lineNo": 1,
                "description": "Anvil",
                "category": "Tools", 
                "quantity": 1.0,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 100.00
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 10.00
                },
                "total": {
                    "currency": "AUD",
                    "amount": 110.00
                },
                "subItems": [
                    {
                        "code": "",
                        "lineNo": 1,
                        "description": "Extra Heavy",
                        "category": "Tools", 
                        "quantity": 1.0,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 10.00
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 1.00
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 11.00
                        }
                    }
                ]
            }
        ]
    },
    "meta": {
        "type": "transaction"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction

Response

Attribute Type Description
_id ID Unique identifier of the transaction
contact ID Reference to the contact this transaction belongs to
visit ID Reference to the visit this transaction is related to
location String The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0._id ID Unique identifier of the item
items.0.code String The product code assigned to this item
items.0.lineNo Integer The display order of this item
items.0.description String The product description given to this item
items.0.category String The product category assigned to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.tax.amount Double The tax charged for this item
items.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String The product code assigned to this sub item
items.0.subItems.0.lineNo Integer The display order of this sub item
items.0.subItems.0.description String The product description given to this item
items.0.subItems.0.category String The product category assigned to this item
items.0.subItems.0.quantity Double The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.subItems.0.unitPrice.amount Double The price of the sub item
items.0.subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.subItems.0.tax.amount Double The tax charged for this sub item
items.0.subItems.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.subItems.0.total.amount Double The total charged for this sub item

PUT /contacts/:_id/transactions/:transaction_id

Update a specific transaction

Request

$ curl -X PUT 'https://{api url}/contacts/{id}/transactions/{transaction_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "visit": "00112233445566778899aabb",
                  "location": "Main St",
                  "reference": "INV0001",
                  "transactedAt": "2018-07-01T12:00:00.000Z",
                  "items": [
                      {
                          "code": "",
                          "lineNo": 1,
                          "description": "Anvil",
                          "category": "Tools",
                          "quantity": 1.0,
                          "unitPrice": {
                              "currency": "AUD",
                              "amount": 100.00
                          },
                          "tax": {
                              "currency": "AUD",
                              "amount": 10.00
                          },
                          "total": {
                              "currency": "AUD",
                              "amount": 110.00
                          },
                          "subItems": [
                              {
                                  "code": "",
                                  "lineNo": 1,
                                  "description": "Extra Heavy",
                                  "category": "Tools",
                                  "quantity": 1.0,
                                  "unitPrice": {
                                      "currency": "AUD",
                                      "amount": 10.00
                                  },
                                  "tax": {
                                      "currency": "AUD",
                                      "amount": 1.00
                                  },
                                  "total": {
                                      "currency": "AUD",
                                      "amount": 11.00
                                  }
                              }
                          ]
                      }
                  ]
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "visit": "00112233445566778899aabb",
        "location": "Main St",
        "reference": "INV0001",
        "transactedAt": "2018-07-01T12:00:00.000Z",
        "items": [
            {
                "_id": "00112233445566778899aabb",
                "code": "",
                "lineNo": 1,
                "description": "Anvil",
                "quantity": 1.0,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 100.00
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 10.00
                },
                "total": {
                    "currency": "AUD",
                    "amount": 110.00
                },
                "subItems": [
                    {
                        "code": "",
                        "lineNo": 1,
                        "description": "Extra Heavy",
                        "quantity": 1.0,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 10.00
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 1.00
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 11.00
                        }
                    }
                ]
            }
        ]
    },
    "meta": {
        "type": "transaction"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction

Body Parameters

Attribute Type Description
visit ID Reference to the visit this transaction is related to
location String The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0.code String The product code assigned to this item
items.0.lineNo Integer The display order of this item
items.0.description String The product description given to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String The taxes currency (USD, AUD, GBP). Currency set to account if not provided
items.0.tax.amount Double The tax charged for this item
items.0.total.currency String The totals currency (USD, AUD, GBP). Currency set to account if not provided
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String The product code assigned to this sub item
items.0.subItems.0.lineNo Integer The display order of this sub item
items.0.subItems.0.description String The product description given to this item
items.0.subItems.0.quantity Double The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.unitPrice.amount Double The price of the sub item
items.0.subItems.0.tax.currency String The taxes currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.tax.amount Double The tax charged for this sub item
items.0.subItems.0.total.currency String The totals currency (USD, AUD, GBP). Currency set to account if not provided
items.0.subItems.0.total.amount Double The total charged for this sub item

Response

Attribute Type Description
_id ID Unique identifier of the transaction
contact ID Reference to the contact this transaction belongs to
visit ID Reference to the visit this transaction is related to
location String The location where this transaction occurred
reference String A reference for this transaction such as the invoice id
transactedAt ISO Date When this transaction occurred
items.0._id ID Unique identifier of the item
items.0.code String The product code assigned to this item
items.0.lineNo Integer The display order of this item
items.0.description String The product description given to this item
items.0.category String The product category assigned to this item
items.0.quantity Double The amount of items purchased
items.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.unitPrice.amount Double The price of the item
items.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.tax.amount Double The tax charged for this item
items.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.total.amount Double The total charged for this item
items.0.subItems.0.code String The product code assigned to this sub item
items.0.subItems.0.lineNo Integer The display order of this sub item
items.0.subItems.0.description String The product description given to this item
items.0.subItems.0.category String The product category assigned to this item
items.0.subItems.0.quantity Double The amount of sub items purchased
items.0.subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
items.0.subItems.0.unitPrice.amount Double The price of the sub item
items.0.subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
items.0.subItems.0.tax.amount Double The tax charged for this sub item
items.0.subItems.0.total.currency String The totals currency (USD, AUD, GBP)
items.0.subItems.0.total.amount Double The total charged for this sub item

DELETE /contacts/:_id/transactions/:transaction_id

Delete a transaction from a contact

Request

$ curl -X DELETE 'https://{api url}/contacts/{id}/transactions/{transaction_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction

POST /contacts/:_id/transactions/:_id/items

Create transaction items for a specific transaction

Request

## Single transaction item request

$ curl -X POST 'https://{api url}/contacts/{id}/transactions/{transaction_id}/items' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "code": "",
                  "lineNo": 1,
                  "description": "Anvil",
                  "category": "Tools",
                  "quantity": 1.0,
                  "unitPrice": {
                      "currency": "AUD",
                      "amount": 100.00
                  },
                  "tax": {
                      "currency": "AUD",
                      "amount": 10.00
                  },
                  "total": {
                      "currency": "AUD",
                      "amount": 110.00
                  },
                  "subItems": [
                      {
                          "code": "",
                          "lineNo": 1,
                          "description": "Extra Heavy",
                          "category": "Tools",
                          "quantity": 1.0,
                          "unitPrice": {
                              "currency": "AUD",
                              "amount": 10.00
                          },
                          "tax": {
                              "currency": "AUD",
                              "amount": 1.00
                          },
                          "total": {
                              "currency": "AUD",
                              "amount": 11.00
                          }
                      }
                  ]
              }
          }
      '

## Multi transaction item request

$ curl -X POST 'https://{api url}/contacts/{id}/transactions/{transaction_id}/items' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "items": [
                  {
                      "data": {
                          "code": "",
                          "lineNo": 1,
                          "description": "Anvil",
                          "quantity": 1.0,
                          "unitPrice": {
                              "currency": "AUD",
                              "amount": 100.00
                          },
                          "tax": {
                              "currency": "AUD",
                              "amount": 10.00
                          },
                          "total": {
                              "currency": "AUD",
                              "amount": 110.00
                          },
                          "subItems": [
                              {
                                  "code": "",
                                  "lineNo": 1,
                                  "description": "Extra Heavy",
                                  "quantity": 1.0,
                                  "unitPrice": {
                                      "currency": "AUD",
                                      "amount": 10.00
                                  },
                                  "tax": {
                                      "currency": "AUD",
                                      "amount": 1.00
                                  },
                                  "total": {
                                      "currency": "AUD",
                                      "amount": 11.00
                                  }
                              }
                          ]
                      }
                  }
              ]
          }
      '

Response

## Single transaction item request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "",
        "lineNo": 1,
        "description": "Anvil",
        "quantity": 1.0,
        "unitPrice": {
            "currency": "AUD",
            "amount": 100.00
        },
        "tax": {
            "currency": "AUD",
            "amount": 10.00
        },
        "total": {
            "currency": "AUD",
            "amount": 110.00
        },
        "subItems": [
            {
                "code": "",
                "lineNo": 1,
                "description": "Extra Heavy",
                "quantity": 1.0,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 10.00
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 1.00
                },
                "total": {
                    "currency": "AUD",
                    "amount": 11.00
                }
            }
        ]
    },
    "meta": {
        "type": "transaction"
    }
}

## Multi transaction item request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "code": "",
                "lineNo": 1,
                "description": "Anvil",
                "quantity": 1,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 100
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 10
                },
                "total": {
                    "currency": "AUD",
                    "amount": 110
                },
                "subItems": [
                    {
                        "code": "456",
                        "lineNo": 1,
                        "description": "Extra Heavy",
                        "quantity": 1,
                        "unitPrice": {
                            "currency": "AUD",
                            "amount": 10
                        },
                        "tax": {
                            "currency": "AUD",
                            "amount": 1
                        },
                        "total": {
                            "currency": "AUD",
                            "amount": 11
                        }
                    }
                ]
            },
            "meta": {
                "type": "transaction"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "failed": 0
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction

Body Parameters

Attribute Type Description
code String The product code assigned to this item
lineNo Integer (Optional) The display order of this item
description String The product description given to this item
category String The product category assigned to this item
quantity Double The amount of items purchased
unitPrice.currency String (Optional) The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
unitPrice.amount Double The price of the item
tax.currency String (Optional) The taxes currency (USD, AUD, GBP). Currency set to account if not provided
tax.amount Double (Optional) The tax charged for this item
total.currency String (Optional) The totals currency (USD, AUD, GBP). Currency set to account if not provided
total.amount Double The total charged for this item
subItems.0.code String (Optional) The product code assigned to this sub item
subItems.0.lineNo Integer (Optional) The display order of this sub item
subItems.0.description String (Optional) The product description given to this item
subItems.0.category String The product category assigned to this item
subItems.0.quantity Double (Optional) The amount of sub items purchased
subItems.0.unitPrice.currency String (Optional) The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.unitPrice.amount Double (Optional) The price of the sub item
subItems.0.tax.currency String (Optional) The taxes currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.tax.amount Double (Optional) The tax charged for this sub item
subItems.0.total.currency String (Optional) The totals currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.total.amount Double (Optional) The total charged for this sub item

Response

Attribute Type Description
_id ID Unique identifier of the item
code String The product code assigned to this item
lineNo Integer The display order of this item
description String The product description given to this item
category String The product category assigned to this item
quantity Double The amount of items purchased
unitPrice.currency String The unit prices currency (USD, AUD, GBP)
unitPrice.amount Double The price of the item
tax.currency String The taxes currency (USD, AUD, GBP)
tax.amount Double The tax charged for this item
total.currency String The totals currency (USD, AUD, GBP)
total.amount Double The total charged for this item
subItems.0.code String The product code assigned to this sub item
subItems.0.lineNo Integer The display order of this sub item
subItems.0.description String The product description given to this item
subItems.0.category String The product category assigned to this item
subItems.0.quantity Double The amount of sub items purchased
subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
subItems.0.unitPrice.amount Double The price of the sub item
subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
subItems.0.tax.amount Double The tax charged for this sub item
subItems.0.total.currency String The totals currency (USD, AUD, GBP)
subItems.0.total.amount Double The total charged for this sub item

PUT /contacts/:_id/transactions/:transaction_id/items/:item_id

Update a specific transaction item

Request

$ curl -X PUT 'https://{api url}/contacts/{id}/transactions/{transaction_id}/items/{item_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "code": "",
                  "lineNo": 1,
                  "description": "Anvil",
                  "category": "Tools",
                  "quantity": 1.0,
                  "unitPrice": {
                      "currency": "AUD",
                      "amount": 100.00
                  },
                  "tax": {
                      "currency": "AUD",
                      "amount": 10.00
                  },
                  "total": {
                      "currency": "AUD",
                      "amount": 110.00
                  },
                  "subItems": [
                      {
                          "code": "",
                          "lineNo": 1,
                          "description": "Extra Heavy",
                          "category": "Tools",
                          "quantity": 1.0,
                          "unitPrice": {
                              "currency": "AUD",
                              "amount": 10.00
                          },
                          "tax": {
                              "currency": "AUD",
                              "amount": 1.00
                          },
                          "total": {
                              "currency": "AUD",
                              "amount": 11.00
                          }
                      }
                  ]
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "",
        "lineNo": 1,
        "description": "Anvil",
        "category": "Tools",
        "quantity": 1.0,
        "unitPrice": {
            "currency": "AUD",
            "amount": 100.00
        },
        "tax": {
            "currency": "AUD",
            "amount": 10.00
        },
        "total": {
            "currency": "AUD",
            "amount": 110.00
        },
        "subItems": [
            {
                "code": "",
                "lineNo": 1,
                "description": "Extra Heavy",
                "category": "Tools",
                "quantity": 1.0,
                "unitPrice": {
                    "currency": "AUD",
                    "amount": 10.00
                },
                "tax": {
                    "currency": "AUD",
                    "amount": 1.00
                },
                "total": {
                    "currency": "AUD",
                    "amount": 11.00
                }
            }
        ]
    },
    "meta": {
        "type": "transaction"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction
item_id ID Unique identifier of the transaction item

Body Parameters

Attribute Type Description
code String The product code assigned to this item
lineNo Integer The display order of this item
description String The product description given to this item
category String The product category assigned to this item
quantity Double The amount of items purchased
unitPrice.currency String The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
unitPrice.amount Double The price of the item
tax.currency String The taxes currency (USD, AUD, GBP). Currency set to account if not provided
tax.amount Double The tax charged for this item
total.currency String The totals currency (USD, AUD, GBP). Currency set to account if not provided
total.amount Double The total charged for this item
subItems.0.code String The product code assigned to this sub item
subItems.0.lineNo Integer The display order of this sub item
subItems.0.description String The product description given to this item
subItems.0.category String The product category assigned to this item
subItems.0.quantity Double The amount of sub items purchased
subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.unitPrice.amount Double The price of the sub item
subItems.0.tax.currency String The taxes currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.tax.amount Double The tax charged for this sub item
subItems.0.total.currency String The totals currency (USD, AUD, GBP). Currency set to account if not provided
subItems.0.total.amount Double The total charged for this sub item

Response

Attribute Type Description
_id ID Unique identifier of the item
code String The product code assigned to this item
lineNo Integer The display order of this item
description String The product description given to this item
category String The product category assigned to this item
quantity Double The amount of items purchased
unitPrice.currency String The unit prices currency (USD, AUD, GBP)
unitPrice.amount Double The price of the item
tax.currency String The taxes currency (USD, AUD, GBP)
tax.amount Double The tax charged for this item
total.currency String The totals currency (USD, AUD, GBP)
total.amount Double The total charged for this item
subItems.0.code String The product code assigned to this sub item
subItems.0.lineNo Integer The display order of this sub item
subItems.0.description String The product description given to this item
subItems.0.category String The product category assigned to this item
subItems.0.quantity Double The amount of sub items purchased
subItems.0.unitPrice.currency String The unit prices currency (USD, AUD, GBP)
subItems.0.unitPrice.amount Double The price of the sub item
subItems.0.tax.currency String The taxes currency (USD, AUD, GBP)
subItems.0.tax.amount Double The tax charged for this sub item
subItems.0.total.currency String The totals currency (USD, AUD, GBP)
subItems.0.total.amount Double The total charged for this sub item

DELETE /contacts/:_id/transactions/:transaction_id/items/:item_id

Delete an item from a transaction

Request

$ curl -X DELETE 'https://{api url}/contacts/{id}/transactions/{transaction_id}/items/{item_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
transaction_id ID Unique identifier of the transaction
item_id ID Unique identifier of the transaction item

GET /contacts/:_id/visits

Retrieve visits/bookings for a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/visits' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "bookingDate": "2018-07-01T12:00:00.000Z",
                "pax": 1,
                "status": "booked",
                "checkIn": "2024-03-01T12:00:00.000Z",
                "checkOut": "2024-03-01T14:00:00.000Z",
                "checkInFlag": true,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2024-03-01T14:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "externalId": "123456"
            },
            "meta": {
                "type": "visit"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/contacts/00112233445566778899aabb/visits"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Response

Attribute Type Description
_id ID Unique identifier of the visit
contact ID Reference to the contact this visit belongs to
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String The status of the visit (booked or cancelled)
checkIn ISO Date The date and time the booking was attended
checkOut ISO Date The date and time the booking was completed
checkInFlag Boolean Whether the booking was attended
deleted Boolean Whether this visit has been deleted or not
created ISO Date The date and time the visit was created
createdBy ID The ID of the user that created the visit
modified ISO Date The date and time the visit was last modified
modifiedBy ID The ID of the user that last modified the visit
externalId String Unique identifier of the visit in an external system

POST /contacts/:_id/visits

Create a new visit/booking for a specific contact

Request

## Single visit request

$ curl -X POST 'https://{api url}/contacts/{id}/visits' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "bookingDate": "2018-07-01T12:00:00.000Z",
                  "pax": 1,
                  "checkIn": "2018-07-01T12:00:00.000Z",
                  "status": "booked",
                  "checkInFlag": true
              }
          }
      '

## Multi visit request

$ curl -X POST 'https://{api url}/contacts/{id}/visit' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "items": [
                  {
                      "data": {
                          "bookingDate": "2018-07-01T12:00:00.000Z",
                          "pax": 1,
                          "checkIn": "2018-07-01T12:00:00.000Z",
                          "status": "booked",
                          "checkInFlag": true
                      }
                  }
              ]
          }
      '

Response

## Single visit request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "bookingDate": "2018-07-01T12:00:00.000Z",
        "pax": 1,
        "status": "booked",
        "checkIn": "2018-07-01T12:00:00.000Z",
        "checkInFlag": true,
        "deleted": false,
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "visit"
    }
}

## Multi visit request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "contact": "00112233445566778899aabb",
                "bookingDate": "2018-07-01T12:00:00.000Z",
                "pax": 1,
                "status": "booked",
                "checkIn": "2018-07-01T12:00:00.000Z",
                "checkInFlag": true,
                "deleted": false,
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb"
            },
            "meta": {
                "type": "visit"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "failed": 0
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact

Body Parameters

Attribute Type Description
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String (Optional) The status of the visit (booked or cancelled). If omitted the status will be set to "booked".
checkIn ISO Date (Optional) The date and time the booking was attended. If omitted and 'checkInFlag' is set to 'true', the current date and time will be set. Otherwise it will be empty.
checkInFlag Boolean (Optional) Whether the booking was attended. If omitted and 'checkIn' is set to a valid date and time, the value will be set to 'true'. Otherwise it will be set to 'false'.

Response

Attribute Type Description
_id ID Unique identifier of the visit
contact ID Reference to the contact this visit belongs to
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String The status of the visit (booked or cancelled)
checkIn ISO Date The date and time the booking was attended
checkInFlag Boolean Whether the booking was attended
deleted Boolean Whether this visit has been deleted or not
created ISO Date The date and time the visit was created
createdBy ID The ID of the user that created the visit
modified ISO Date The date and time the visit was last modified
modifiedBy ID The ID of the user that last modified the visit

GET /contacts/:_id/visits/:visit_id

Retrieve a specific visit/booking for a specific contact

Request

$ curl -X GET 'https://{api url}/contacts/{id}/visits/{visit_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "bookingDate": "2018-07-01T12:00:00.000Z",
        "pax": 1,
        "status": "booked",
        "checkIn": "2018-07-01T12:00:00.000Z",
        "checkInFlag": true,
        "deleted": false,
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "visit"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
visit_id ID Unique identifier of the visit

Response

Attribute Type Description
_id ID Unique identifier of the visit
contact ID Reference to the contact this visit belongs to
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String The status of the visit (booked or cancelled)
checkIn ISO Date The date and time the booking was attended
checkInFlag Boolean Whether the booking was attended
deleted Boolean Whether this visit has been deleted or not
created ISO Date The date and time the visit was created
createdBy ID The ID of the user that created the visit
modified ISO Date The date and time the visit was last modified
modifiedBy ID The ID of the user that last modified the visit

PUT /contacts/:_id/visits/:visit_id

Update an existing visit/booking for a specific contact

Request

$ curl -X PUT 'https://{api url}/contacts/{id}/visits/{visit_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "bookingDate": "2018-07-01T12:00:00.000Z",
                  "pax": 1,
                  "checkIn": "2018-07-01T12:00:00.000Z",
                  "status": "booked",
                  "checkInFlag": true,
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "contact": "00112233445566778899aabb",
        "bookingDate": "2018-07-01T12:00:00.000Z",
        "pax": 1,
        "status": "booked",
        "checkIn": "2018-07-01T12:00:00.000Z",
        "checkInFlag": true,
        "deleted": false,
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "visit"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
visit_id ID Unique identifier of the visit

Body Parameters

Attribute Type Description
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String (Optional) The status of the visit (booked or cancelled). If omitted the status will be set to "booked".
checkIn ISO Date (Optional) The date and time the booking was attended. If omitted and 'checkInFlag' is set to 'true', the current date and time will be set. Otherwise it will be empty.
checkInFlag Boolean (Optional) Whether the booking was attended. If omitted and 'checkIn' is set to a valid date and time, the value will be set to 'true'. Otherwise it will be set to 'false'.

Response

Attribute Type Description
_id ID Unique identifier of the visit
contact ID Reference to the contact this visit belongs to
bookingDate ISO Date The date and time the visit happened or will happen
pax Integer Number of people attending
status String The status of the visit (booked or cancelled)
checkIn ISO Date The date and time the booking was attended
checkInFlag Boolean Whether the booking was attended
deleted Boolean Whether this visit has been deleted or not
created ISO Date The date and time the visit was created
createdBy ID The ID of the user that created the visit
modified ISO Date The date and time the visit was last modified
modifiedBy ID The ID of the user that last modified the visit

DELETE /contacts/:_id/visits/:visit_id

Delete a visit/booking from a specific contact

Request

$ curl -X DELETE 'https://{api url}/contacts/{id}/visits/{visit_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the contact
visit_id ID Unique identifier of the visit

GET /campaigns/export

Retrieve a list of campaign folders available in the account

Request

$ curl -X GET 'https://{api url}/campaigns/export' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "totalSent": 28,
                "totalDraft": 12,
                "totalAwaitingApproval": 0,
                "_id": "0045707439056834603095809683086",
                "name": "Test",
                "lastCommunication": "2022-11-30T04:59:00.347Z",
                "archived": false,
                "account": "00457078276457439056834603095809683086",
                "campaignType": [
                    "Email",
                    "Sms"
                ],
                "emailChannels": 38,
                "smsChannels": 2,
                "pushNotificationChannels": 0,
                "emails": 112988,
                "emailsSent": 10,
                "emailsBlocked": 5053,
                "emailsFailed": 4605,
                "emailsDeleted": 0,
                "emailsOpen": 0,
                "emailsUniqueOpen": 0,
                "emailsClicked": 0,
                "emailsUniqueClicked": 0,
                "emailsOptout": 0,
                "emailsAutoOptout": 0,
                "emailsBounced": 0,
                "emailsSpam": 0,
                "sms": 0,
                "smsRecipients": 0,
                "smsSent": 0,
                "smsBlocked": 0,
                "smsSystemBlocked": 0,
                "smsFailed": 0,
                "smsDeleted": 0,
                "smsOptout": 0,
                "smsAutoOptout": 0,
                "smsBounced": 0,
                "pushNotification": 0,
                "pushNotificationRecipients": 0,
                "pushNotificationSent": 0,
                "pushNotificationFailed": 0,
                "pushNotificationDeleted": 0,
                "totalAutomationSent": 4
            },
            "meta": {
                "type": "campaign"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 2,
        "links": {
            "totalPage": 1,
            "self": "/campaigns/export?pageSize=50&page=1",
            "firstPage": "/campaigns/export?pageSize=50&page=1",
            "lastPage": "/campaigns/export?pageSize=50&page=1"
        }
    }
}

Response

Attribute Type Description
_id ID Unique identifier of the campaign folder
account ID Reference to the account the campaign folder belongs to
archived Boolean If the campaign folder has been archived
campaignType Array of Strings List of campaign types the folder contains
emailChannels Integer Number of Email Channels in the folder
emails Integer Number of targeted contacts for emails
emailsAutoOptout Integer Number of email opt outs by client unsubscribe
emailsBlocked Integer Number of emails blocked by system blacklist
emailsBounced Integer Number of emails bounced
emailsClicked Integer Number of email clicks
emailsDeleted Integer Number of emails deleted
emailsFailed Integer Number of emails failed to deliver
emailsOpen Integer Number of email opens
emailsOptOut Integer Number of email opt outs by Unsubscribe link click
emailsSent Integer Who created the field
emailsSpam Integer Number of emails in spam folder
emailsUniqueClicked Integer Number of unique email clicks
emailsUniqueOpen String A selectable option available for gender, multi and single select fields
emailsUniqueClicked Integer Number of unique email clicks
lastCommunication ISO Date Date time when the latest communication went out for this campaign folder
name String Name of the campaign folder
pushNotification Integer Number of push notifications
pushNotificationChannels Integer Number of push notification channels in the folder
pushNotificationDeleted Integer Number of push notifications deleted
pushNotificationFailed Integer Number of push notification failed
pushNotificationRecipients Integer Number of targeted contacts for push notifications
pushNotificationSent Integer Number of push notifications sent
sms Integer Number of unique email clicks
smsAutoOptout Integer Number of SMS credits used
smsBlocked Integer Number of SMS blocked
smsBounced Integer Number of SMS bounced
smsChannels Integer Number of SMS channels in the folder
smsDeleted Integer Number of SMS deleted
smsFailed Integer Number of SMS fails
smsOptout Integer Number of SMS opt outs
smsRecipients Integer Number of targeted contacts for SMS
smsSent Integer Number of SMS delivered
smsSystemBlocked Integer Number of SMS blocked by system blacklist
totalAutomationSent Integer Number of automation campaigns sent
totalAwaitingApproval Integer Number of channels awaiting master accounts approval
totalDraft Integer Number of channels in draft status
totalSent Integer Number of channels sent

GET /campaigns/:_id/channels/export

Retrieve a list of campaigns available in a specific campaign folder

Request

$ curl -X GET 'https://{api url}/campaigns/:_id/channels/export' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "9843759347673503009809380945806",
                "abTest": {},
                "statistics": {
                    "emails": 1,
                    "emailsSent": 1,
                    "emailsBlocked": 0,
                    "emailsFailed": 0,
                    "emailsDeleted": 0,
                    "emailsOpen": 2,
                    "emailsUniqueOpen": 1,
                    "emailsClicked": 0,
                    "emailsUniqueClicked": 0,
                    "emailsOptout": 0,
                    "emailsAutoOptout": 0,
                    "emailsBounced": 0,
                    "emailsSpam": 0,
                    "sms": 0,
                    "smsRecipients": 0,
                    "smsSent": 0,
                    "smsBlocked": 0,
                    "smsSystemBlocked": 0,
                    "smsFailed": 0,
                    "smsDeleted": 0,
                    "smsOptout": 0,
                    "smsBounced": 0,
                    "pushNotification": 0,
                    "pushNotificationRecipients": 0,
                    "pushNotificationSent": 0,
                    "pushNotificationFailed": 0,
                    "pushNotificationDeleted": 0,
                    "reasons": {}
                },
                "channelType": "email",
                "campaign": "983476907890350649337645078630983403",
                "createdBy": "347096078305378098639486039986",
                "status": "sent",
                "account": "983476987369787630896709739681",
                "created": "2023-12-20T04:52:11.406Z",
                "modified": "2023-12-20T04:52:49.023Z",
                "fromName": "Connect Test",
                "replyTo": "test@test.com",
                "from": "test@test.com",
                "subject": "Dummy Subject",
                "content": "6582731704fefaa6a19de01e",
                "sent": "2023-12-20T04:52:51.305Z",
                "firstCommunication": "2023-12-20T04:53:13.443Z",
                "lastCommunication": "2023-12-20T04:53:13.443Z"
            },
            "meta": {
                "type": "channel"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 31,
        "links": {
            "totalPage": 10,
            "self": "/campaigns/983476907890350649337645078630983403/channels/export?pageSize=1&page=1",
            "firstPage": "/campaigns/983476907890350649337645078630983403/channels/export?pageSize=1&page=1",
            "nextPage": "/campaigns/983476907890350649337645078630983403/channels/export?pageSize=1&page=2",
            "lastPage": "/campaigns/983476907890350649337645078630983403/channels/export?pageSize=1&page=31"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the campaign folder

Response

Attribute Type Description
_id ID Unique Identifier for a Campaign
abTest.abType String Testing strategy
abTest.category String AB test category
abTest.criteria String Testing criteria
abTest.group String AB test group the campaign belongs to
abTest.groupIndex Integer AB test group index
abTest.isWinner Boolean Winning channel
abTest.percentage Integer Percentage of recipients in A/B test
abTest.testPeriod Integer Test duration
account ID Reference to the account the campaign belongs to
campaign ID Unique Identifier of the Campaign Folder that the campaign belongs to
channelType String Campaign type: Email, SMS, Push Notification
created ISO Date Created date time for the campaign
firstCommunication ISO Date Date time when the first communication went out for this campaign
from String From Email/Sender Id used to send a campaign
fromName String From name used in Email Campaigns
lastCommunication ISO Date Date time when the latest communication went out for this campaign
modified ISO Date Last modified date time for the campaign
sent ISO Date Date time when the campaign was/is supposed to be sent on
statistics.emails Integer Number of targeted contacts for emails
statistics.emailsAutoOptout Integer Number of email opt outs by client unsubscribe
statistics.emailsBlocked Integer Number of emails blocked by system blacklist
statistics.emailsBounced Integer Number of emails bounced
statistics.emailsClicked Integer Number of email clicks
statistics.emailsDeleted Integer Number of emails deleted
statistics.emailsFailed Integer Number of emails failed to deliver
statistics.emailsOpen Integer Number of email opens
statistics.emailsOptOut Integer Number of email opt outs by Unsubscribe link click
statistics.emailsSent Integer Number of emails delivered
statistics.emailsSpam Integer Number of emails in spam folder
statistics.emailsUniqueClicked Integer Number of unique email clicks
statistics.emailsUniqueOpen Integer Number of unique email opens
statistics.pushNotification Integer Number of push notifications
statistics.pushNotificationDeleted Integer Number of push notifications deleted
statistics.pushNotificationFailed Integer Number of push notifications failed
statistics.pushNotificationRecipients Integer Number of targeted contacts for push notifications
statistics.pushNotificationSent Integer Number of push notifications sent
statistics.reasons Object Object containing opt out reasons with their respective counts, excludes auto opt out
statistics.sms Integer Number of SMS credits used
statistics.smsBlocked Integer Number of SMS blocked
statistics.smsBounced Integer Number of SMS bounced
statistics.smsDeleted Integer Number of SMS deleted
statistics.smsFailed Integer Number of SMS fails
statistics.smsOptout Integer Number of SMS opt outs
statistics.smsRecipients Integer Number of targeted contacts for SMS
statistics.smsSent Integer Number of SMS delivered
statistics.smsSystemBlocked Integer Number of SMS blocked by system blacklist
status String Campaign status
subject String Email Subject
thumbnailURL String Content Thumbnail URL

GET /campaigns/:_id/channels/:_channelId/recipients/export

Retrieve a list of campaigns available in a specific campaign folder

Request

$ curl -X GET 'https://{api url}/campaigns/:_id/channels/:_channelId/recipients/export' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "02893456987035975928670939037690",
                "channel": "2345608975390273765893896792307459043",
                "sentDate": "2023-12-20T05:17:22.007Z",
                "contactId": "4687037460930367293073628769853",
                "deliveredDate": "2023-12-20T05:17:23.196Z",
                "open": {
                    "ipAddress": "72.115.153.69",
                    "agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0",
                    "device": "Desktop",
                    "client": "Microsoft Edge",
                    "os": "Windows 10",
                    "actionType": "EMAIL_OPENED",
                    "openCount": 2,
                    "geo": {
                        "geoType": "Point",
                        "coordinates": [
                            -97.822,
                            37.751
                        ]
                    },
                    "location": {
                        "country": "US"
                    },
                    "occurred": "2023-12-20T05:17:28.898Z"
                }
            },
            "meta": {
                "type": "campaign"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "totalPage": 1,
            "self": "/campaigns/983476907890350649337645078630983403/channels/2345608975390273765893896792307459043/recipients/export?pageSize=50&page=1",
            "firstPage": "/campaigns/983476907890350649337645078630983403/channels/2345608975390273765893896792307459043/recipients/export?pageSize=50&page=1",
            "lastPage": "/campaigns/983476907890350649337645078630983403/channels/2345608975390273765893896792307459043/recipients/export?pageSize=50&page=1"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the campaign folder
_channelId ID Unique identifier of the campaign

Response

Attribute Type Description
_id ID Unique identifier for recipient
channel ID Reference to the campaign the recipient belongs to
click Object Information about the recipients click action
deliveredDate ISO Date The date time that the communication was deliver to the recipient
open Object Information about the recipients open action
sentDate ISO Date The date time that the communication was sent to the recipient

GET /fields

Retrieve a list of fields available in the account

Request

$ curl -X GET 'https://{api url}/fields' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "account": "00112233445566778899aabb",
                "collectionType": "contact",
                "fieldType": "email",
                "name": "email",
                "label": "Email",
                "order": 1,
                "defaultValue": null,
                "required": true,
                "hidden": false,
                "readOnly": false,
                "systemField": true,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "options": [
                    {
                        "value": "",
                        "order": 0,
                        "deleted": false
                    }
                ]
            },
            "meta": {
                "type": "field"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/fields"
        }
    }
}

Response

Attribute Type Description
_id ID Unique identifier of the field
account ID Reference to the account the field belongs to
collectionType String Where the field collects the data. Currently only 'contact' is supported
fieldType String The type of data stored in this field
name String The name of the field used as the key in the corresponding collection storing the information
label String The display name of the field
order Integer The order in which this field is displayed
defaultValue String The default value assigned to the field if no data is available during creation
required Boolean Whether this field is required in the corresponding collection storing the information
hidden Boolean Whether this field is hidden from the users
readOnly Boolean Whether this field is editable by a user
systemField Boolean Whether ihis field is a predefined field used by the platform
deleted Boolean Has this field been flagged as deleted and shouldn't be shown
created ISO Date When the field was created
createdBy ID Who created the field
modified ISO Date When the field was last modified
modifiedBy ID Who last modified the field
options.0.value String A selectable option available for gender, multi and single select fields
options.0.order Integer The display order of the field option
options.0.deleted Boolean Has this option been removed

POST /fields

Create fields for a specific account

Field types supported are

Type Description
string Single line text field
textblock Multi line text field
email Email field
mobile Mobile/cell phone field
dob Date of birth field
gender Gender field (m/f)
number Numeric field
date Date only field
datetime Date & time field
time Time only field
single Single select field
multi Multi select field
boolean Boolean field (true/false)

Request

## Single field request

$ curl -X POST 'https://{api url}/fields' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "fieldType": "multi",
                  "label": "My New Multi Select",
                  "defaultValue": "hello world",
                  "required": false,
                  "options": [
                      {
                             "value": "hello world"
                      }
                  ]
              }
          }
      '

## Multi field request

$ curl -X POST 'https://{api url}/fields' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
               "items": [
                  {
                      "data": {
                          "fieldType": "multi",
                          "label": "My New Multi Select",
                          "defaultValue": "hello world",
                          "required": false,
                          "options": [
                              {
                                     "value": "hello world"
                              }
                          ]
                      }
                  }
              ]
          }
      '

Response

## Single field request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "collectionType": "contact",
        "fieldType": "multi",
        "name": "myNewMultiSelect",
        "label": "My New Multi Select",
        "order": 1,
        "defaultValue": "hello world",
        "required": false,
        "hidden": false,
        "readOnly": false,
        "systemField": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "options": [
            {
                "value": "hello world",
                "order": 0,
                "deleted": false
            }
        ]
    },
    "meta": {
        "type": "field"
    }
}

## Multi field request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "account": "00112233445566778899aabb",
                "collectionType": "contact",
                "fieldType": "multi",
                "name": "myNewMultiSelect",
                "label": "My New Multi Select",
                "order": 1,
                "defaultValue": "hello world",
                "required": false,
                "hidden": false,
                "readOnly": false,
                "systemField": false,
                "deleted": false,
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "options": [
                    {
                        "value": "hello world",
                        "order": 0,
                        "deleted": false
                    }
                ]
            },
            "meta": {
                "type": "field"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "failed": 0
    }
}

Body Parameters

Attribute Type Description
fieldType String The type of data stored in this field based on one of the supported type above
label String The display name of the field
defaultValue String (Optional) The default value assigned to the field if no data is available during creation
required Boolean (Optional) Whether this field is required in the corresponding collection storing the information
options.0.value String (Optional) A selectable option available for multi and single select fields

Response

Attribute Type Description
_id ID Unique identifier of the field
account ID Reference to the account the field belongs to
collectionType String Where the field collects the data. Currently only 'contact' is supported
fieldType String The type of data stored in this field
name String The name of the field used as the key in the corresponding collection storing the information
label String The display name of the field
order Integer The order in which this field is displayed
defaultValue String The default value assigned to the field if no data is available during creation
required Boolean Whether this field is required in the corresponding collection storing the information
hidden Boolean Whether this field is hidden from the users
readOnly Boolean Whether this field is editable by a user
systemField Boolean Whether ihis field is a predefined field used by the platform
deleted Boolean Has this field been flagged as deleted and shouldn't be shown
created ISO Date When the field was created
createdBy ID Who created the field
modified ISO Date When the field was last modified
modifiedBy ID Who last modified the field
options.0.value String A selectable option available for gender, multi and single select fields
options.0.order Integer The display order of the field option
options.0.deleted Boolean Has this option been removed

GET /fields/:_id

Retrieve a specific field from an account

Request

$ curl -X GET 'https://{api url}/fields/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "collectionType": "contact",
        "fieldType": "multi",
        "name": "myNewMultiSelect",
        "label": "My New Multi Select",
        "order": 1,
        "defaultValue": "hello world",
        "required": false,
        "hidden": false,
        "readOnly": false,
        "systemField": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "options": [
            {
                "value": "hello world",
                "order": 0,
                "deleted": false
            }
        ]
    },
    "meta": {
        "type": "field"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the field

Response

Attribute Type Description
_id ID Unique identifier of the field
account ID Reference to the account the field belongs to
collectionType String Where the field collects the data. Currently only 'contact' is supported
fieldType String The type of data stored in this field
name String The name of the field used as the key in the corresponding collection storing the information
label String The display name of the field
order Integer The order in which this field is displayed
defaultValue String The default value assigned to the field if no data is available during creation
required Boolean Whether this field is required in the corresponding collection storing the information
hidden Boolean Whether this field is hidden from the users
readOnly Boolean Whether this field is editable by a user
systemField Boolean Whether ihis field is a predefined field used by the platform
deleted Boolean Has this field been flagged as deleted and shouldn't be shown
created ISO Date When the field was created
createdBy ID Who created the field
modified ISO Date When the field was last modified
modifiedBy ID Who last modified the field
options.0.value String A selectable option available for gender, multi and single select fields
options.0.order Integer The display order of the field option
options.0.deleted Boolean Has this option been removed

PUT /fields/:_id

Update a specific field in an account

Request

$ curl -X POST 'https://{api url}/fields/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "label": "My New Multi Select",
                  "defaultValue": "hello world",
                  "required": false,
                  "options": [
                      {
                             "value": "hello world"
                      }
                  ]
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "account": "00112233445566778899aabb",
        "collectionType": "contact",
        "fieldType": "multi",
        "name": "myNewMultiSelect",
        "label": "My New Multi Select",
        "order": 1,
        "defaultValue": "hello world",
        "required": false,
        "hidden": false,
        "readOnly": false,
        "systemField": false,
        "deleted": false,
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "options": [
            {
                "value": "hello world",
                "order": 0,
                "deleted": false
            }
        ]
    },
    "meta": {
        "type": "field"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the field

Body Parameters

Attribute Type Description
label String The display name of the field
defaultValue String The default value assigned to the field if no data is available during creation
required Boolean Whether this field is required in the corresponding collection storing the information
options.0.value String A selectable option available for multi and single select fields

Response

Attribute Type Description
_id ID Unique identifier of the field
account ID Reference to the account the field belongs to
collectionType String Where the field collects the data. Currently only 'contact' is supported
fieldType String The type of data stored in this field
name String The name of the field used as the key in the corresponding collection storing the information
label String The display name of the field
order Integer The order in which this field is displayed
defaultValue String The default value assigned to the field if no data is available during creation
required Boolean Whether this field is required in the corresponding collection storing the information
hidden Boolean Whether this field is hidden from the users
readOnly Boolean Whether this field is editable by a user
systemField Boolean Whether ihis field is a predefined field used by the platform
deleted Boolean Has this field been flagged as deleted and shouldn't be shown
created ISO Date When the field was created
createdBy ID Who created the field
modified ISO Date When the field was last modified
modifiedBy ID Who last modified the field
options.0.value String A selectable option available for gender, multi and single select fields
options.0.order Integer The display order of the field option
options.0.deleted Boolean Has this option been removed

DELETE /fields/:_id

Delete a field from an account

Request

$ curl -X DELETE 'https://{api url}/fields/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 204

Path Parameters

Attribute Type Description
_id ID Unique identifier of the field

GET /forms

Retrieve a list of forms available via the parent account

Request

$ curl -X GET 'https://{api url}/forms' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "name": "Sign Up",
                "account": "00112233445566778899aabb",
                "status": "enabled",
                "created": "2018-07-01T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2018-07-01T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "statistics": {
                    "submissions": 0,
                    "uniqueImpressions": 0,
                    "impressions": 0,
                    "avgImpressionsPerDay": "0.00",
                    "avgSubmissionsPerDay": "0.00",
                    "completionRate": "0.00"
                },
                "lastSubmitted": "2018-07-01T12:00:00.000Z"
            },
            "meta": {
                "type": "webform"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/forms"
        }
    }
}

Response

Attribute Type Description
_id ID Unique identifier of the form
name String Name given to the form
account ID Account the form belongs to
status String Current status of the form (enabled, disabled, deleted)
created ISO Date When the form was created
createdBy ID The user that created the form
modified ISO Date When the form was last modified
modifiedBy ID The user that last modified the form
statistics.submissions Integer Total number of submissions the form has received
statistics.uniqueImpressions Integer Total number of unique impressions the form has received
statistics.impressions Integer Total number of impressions the form has received
statistics.avgImpressionsPerDay Double Average number of impressions per day
statistics.avgSubmissionsPerDay Double Average number of submissions per day
statistics.completionRate Double The forms completion rate (calculated as submissions / unique impressions)
lastSubmitted ISO Date When the last submission happened

GET /forms/:_id

Retrieve a specific webform in the parent account

Request

$ curl -X GET 'https://{api url}/forms/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Sign Up",
        "account": "00112233445566778899aabb",
        "status": "enabled",
        "created": "2018-07-01T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2018-07-01T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "statistics": {
            "submissions": 0,
            "uniqueImpressions": 0,
            "impressions": 0,
            "avgImpressionsPerDay": "0.00",
            "avgSubmissionsPerDay": "0.00",
            "completionRate": "0.00"
        },
        "lastSubmitted": "2018-07-01T12:00:00.000Z"
    },
    "meta": {
        "type": "webform"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the form

Response

Attribute Type Description
_id ID Unique identifier of the form
name String Name given to the form
account ID Account the form belongs to
status String Current status of the form (enabled, disabled, deleted)
created ISO Date When the form was created
createdBy ID The user that created the form
modified ISO Date When the form was last modified
modifiedBy ID The user that last modified the form
statistics.submissions Integer Total number of submissions the form has received
statistics.uniqueImpressions Integer Total number of unique impressions the form has received
statistics.impressions Integer Total number of impressions the form has received
statistics.avgImpressionsPerDay Double Average number of impressions per day
statistics.avgSubmissionsPerDay Double Average number of submissions per day
statistics.completionRate Double The forms completion rate (calculated as submissions / unique impressions)
lastSubmitted ISO Date When the last submission happened

GET /forms/:_id/code

Retrieve the deployment code (HTML and Javascript) for a specific form

Request

$ curl -X GET 'https://{api url}/forms/{id}/code' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "code": {
            "html": "",
            "script": ""
        },
        "hosted": ""
    },
    "meta": {
        "type": "webform"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the form

Response

Attribute Type Description
code.html String The HTML tag the Javascript requires on the website to attached the form to
code.script String The Javascript version of the form
hosted String The hosted version of the form

GET /forms/:_id/submissions

Retrieve the submissions made on a specific form

Request

$ curl -X GET 'https://{api url}/forms/{id}/submissions' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "status": "accepted",
                "webform": "00112233445566778899aabb",
                "received": "2018-07-01T12:00:00.000Z",
                "post": {
                    "E-mail": "noreply@example.com",
                    "Surname": "Bloggs",
                    "First name": "Joe"
                },
                "verified": "2018-07-01T12:00:00.000Z",
                "contact": "00112233445566778899aabb"
            },
            "meta": {
                "type": "webformSubmission"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/forms/00112233445566778899aabb/submissions"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the form

Response

Attribute Type Description
_id ID Unique identifier of the form submission
status String Current status of the form submission (accepted, pending, declined, verify)
webform ID Reference to the form this submission was received from
received ISO Date The date and time the submission was received
post Object A key / value object of the submission data representing the field and value submitted
verified ISO Date The date and time the submission was verified by the person who submitted it if double opt-in is enabled on the form
contact ID Reference to the contact added or updated in the account by this submission

GET /forms/:_id/submissions/:submission_id

Retrieve a specific submission made on a form

Request

$ curl -X GET 'https://{api url}/forms/{id}/submissions/{submission_id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "status": "accepted",
        "webform": "00112233445566778899aabb",
        "received": "2018-07-01T12:00:00.000Z",
        "post": {
            "E-mail": "noreply@example.com",
            "Surname": "Bloggs",
            "First name": "Joe"
        },
        "verified": "2018-07-01T12:00:00.000Z",
        "contact": "00112233445566778899aabb"
    },
    "meta": {
        "type": "webformSubmission"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the form
submission_id ID Unique identifier of the form submission

Response

Attribute Type Description
_id ID Unique identifier of the form submission
status String Current status of the form submission (accepted, pending, declined, verify)
webform ID Reference to the form this submission was received from
received ISO Date The date and time the submission was received
post Object A key / value object of the submission data representing the field and value submitted
verified ISO Date The date and time the submission was verified by the person who submitted it if double opt-in is enabled on the form
contact ID Reference to the contact added or updated in the account by this submission

GET /offers

Retrieve a list of offers available in the account

Request

$ curl -X GET 'https://{api url}/offers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "name": "Offer 1",
                "description": "Offer 1 description",
                "externalId": "",
                "controller": "contacta",
                "account": "00112233445566778899aabb",
                "created": "2021-04-06T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2021-04-06T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "rules": {
                    "startDatetime": "2021-04-06T12:00:00.000Z",
                    "endDatetime": "2021-04-06T12:00:00.000Z",
                    "voucherLifetime": 1,
                    "maximumVouchers": 1
                }
            },
            "meta": {
                "type": "offer"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/offers"
        }
    }
}

Response

Attribute Type Description
_id ID Unique identifier of the offer
name String The name of the offer as set by the user
description String Offer description
externalId String Reference to a third-party system
controller String The system responsible for maintaining offer vouchers
account ID Account the offer belongs to
created ISO Date When the offer was created
createdBy ID Who created the offer
modified ISO Date When the offer was last modified
modifiedBy ID Who last modified the offer
rules.startDatetime ISO Date Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer Number of vouchers that can be generated for this offer

POST /offers

Create offers for a specific account

Request

## Single offer request

$ curl -X POST 'https://{api url}/offers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "name": "Offer 1",
                  "description": "Offer 1 description",
                  "externalId": "",
                  "controller": "",
                  "rules": {
                      "startDatetime": "2021-04-06T12:00:00.000Z",
                      "endDatetime": "2021-04-06T12:00:00.000Z",
                      "voucherLifetime": 1,
                      "maximumVouchers": 1
                  }
              }
          }
      '

## Multi offer request

$ curl -X POST 'https://{api url}/offers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
               "items": [
                  {
                      "data": {
                          "name": "Offer 1",
                          "description": "Offer 1 description",
                          "externalId": "",
                          "controller": "",
                          "rules": {
                              "startDatetime": "2021-04-06T12:00:00.000Z",
                              "endDatetime": "2021-04-06T12:00:00.000Z",
                              "voucherLifetime": 1,
                              "maximumVouchers": 1
                          }
                      }
                  }
              ]
          }
      '

Response

## Single offer request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Offer 1",
        "description": "Offer 1 description",
        "externalId": "",
        "controller": "contacta",
        "account": "00112233445566778899aabb",
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "rules": {
            "startDatetime": "2021-04-06T12:00:00.000Z",
            "endDatetime": "2021-04-06T12:00:00.000Z",
            "voucherLifetime": 1,
            "maximumVouchers": 1
        }
    },
    "meta": {
        "type": "offer"
    }
}

## Multi offer request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "name": "Offer 1",
                "description": "Offer 1 description",
                "externalId": "",
                "controller": "contacta",
                "account": "00112233445566778899aabb",
                "created": "2021-04-06T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "rules": {
                    "startDatetime": "2021-04-06T12:00:00.000Z",
                    "endDatetime": "2021-04-06T12:00:00.000Z",
                    "voucherLifetime": 1,
                    "maximumVouchers": 1
                }
            },
            "meta": {
                "type": "offer"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "updated": 0,
        "failed": 0
    }
}

Body Parameters

Attribute Type Description
name String The name of the offer as set by the user
description String (Optional) Offer description
externalId String (Optional) Reference to a third-party system
controller String (Optional) The system responsible for maintaining offer vouchers
rules.startDatetime ISO Date (Optional) Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date (Optional) Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer (Optional) Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer (Optional) Number of vouchers that can be generated for this offer

Response

Attribute Type Description
_id ID Unique identifier of the offer
name String The name of the offer as set by the user
description String Offer description
externalId String Reference to a third-party system
controller String The system responsible for maintaining offer vouchers
account ID Account the offer belongs to
created ISO Date When the offer was created
createdBy ID Who created the offer
rules.startDatetime ISO Date Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer Number of vouchers that can be generated for this offer

GET /offers/:_id

Retrieve a specific offer from an account

Request

$ curl -X GET 'https://{api url}/offers/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Offer 1",
        "description": "Offer 1 description",
        "externalId": "",
        "controller": "contacta",
        "account": "00112233445566778899aabb",
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "rules": {
            "startDatetime": "2021-04-06T12:00:00.000Z",
            "endDatetime": "2021-04-06T12:00:00.000Z",
            "voucherLifetime": 1,
            "maximumVouchers": 1
        }
    },
    "meta": {
        "type": "offer"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer

Response

Attribute Type Description
_id ID Unique identifier of the offer
name String The name of the offer as set by the user
description String Offer description
externalId String Reference to a third-party system
controller String The system responsible for maintaining offer vouchers
account ID Account the offer belongs to
created ISO Date When the offer was created
createdBy ID Who created the offer
modified ISO Date When the offer was last modified
modifiedBy ID Who last modified the offer
rules.startDatetime ISO Date Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer Number of vouchers that can be generated for this offer

PUT /offers/:_id

Update a specific offer in an account

Request

$ curl -X PUT 'https://{api url}/offers/{id}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "name": "Offer 1",
                  "description": "Offer 1 description",
                  "externalId": "",
                  "controller": "",
                  "rules": {
                      "startDatetime": "2021-04-06T12:00:00.000Z",
                      "endDatetime": "2021-04-06T12:00:00.000Z",
                      "voucherLifetime": 1,
                      "maximumVouchers": 1
                  }
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Offer 1",
        "description": "Offer 1 description",
        "externalId": "",
        "controller": "contacta",
        "account": "00112233445566778899aabb",
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "rules": {
            "startDatetime": "2021-04-06T12:00:00.000Z",
            "endDatetime": "2021-04-06T12:00:00.000Z",
            "voucherLifetime": 1,
            "maximumVouchers": 1
        }
    },
    "meta": {
        "type": "offer"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer

Body Parameters

Attribute Type Description
name String (Optional) The name of the offer as set by the user
description String (Optional) Offer description
externalId String (Optional) Reference to a third-party system
controller String (Optional) The system responsible for maintaining offer vouchers
rules.startDatetime ISO Date (Optional) Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date (Optional) Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer (Optional) Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer (Optional) Number of vouchers that can be generated for this offer

Response

Attribute Type Description
_id ID Unique identifier of the offer
name String The name of the offer as set by the user
description String Offer description
externalId String Reference to a third-party system
controller String The system responsible for maintaining offer vouchers
account ID Account the offer belongs to
created ISO Date When the offer was created
createdBy ID Who created the offer
modified ISO Date When the offer was last modified
modifiedBy ID Who last modified the offer
rules.startDatetime ISO Date Datetime of which all vouchers that belong to this offer are valid from
rules.endDatetime ISO Date Datetime of which all vouchers that belong to this offer expire
rules.voucherLifetime Integer Number of days a voucher is valid for from the day it is issued
rules.maximumVouchers Integer Number of vouchers that can be generated for this offer

GET /offers/:_id/vouchers

Retrieve the vouchers in a specific offer

Request

$ curl -X GET 'https://{api url}/offers/{id}/vouchers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "code": "0000",
                "account": "00112233445566778899aabb",
                "expiryDatetime": "2021-04-06T12:00:00.000Z",
                "offer": "00112233445566778899aabb",
                "sent": "2021-04-06T12:00:00.000Z",
                "contact": "00112233445566778899aabb",
                "channel": "00112233445566778899aabb",
                "recipient": "00112233445566778899aabb",
                "formSubmission": "00112233445566778899aabb",
                "redeemed": {
                    "on": "2021-04-06T12:00:00.000Z"
                },
                "created": "2021-04-06T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2021-04-06T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb"
            },
            "meta": {
                "type": "voucher"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/offers/00112233445566778899aabb/vouchers"
        }
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher

POST /offers/:_id/vouchers

Create vouchers for a specific offer

Request

## Single voucher request

$ curl -X POST 'https://{api url}/offers/{id}/vouchers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "code": "0000",
                  "expiryDatetime": "2021-04-06T12:00:00.000Z"
              }
          }
      '

## Multi voucher request

$ curl -X POST 'https://{api url}/offers/{id}/vouchers' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
               "items": [
                  {
                      "data": {
                          "code": "0000",
                          "expiryDatetime": "2021-04-06T12:00:00.000Z"
                      }
                  }
              ]
          }
      '

Response

## Single voucher request

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "voucher"
    }
}

## Multi voucher request

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "code": "0000",
                "account": "00112233445566778899aabb",
                "expiryDatetime": "2021-04-06T12:00:00.000Z",
                "offer": "00112233445566778899aabb",
                "created": "2021-04-06T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb"
            },
            "meta": {
                "type": "voucher"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "created": 1,
        "updated": 0,
        "failed": 0
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer

Body Parameters

Attribute Type Description
code String The unique voucher code
expiryDatetime ISO Date (Optional) Voucher expiry datetime

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
created ISO Date When the voucher was created
createdBy ID Who created the voucher

GET /offers/:_id/vouchers/:_voucherId

Retrieve a specific voucher from an offer

Request

$ curl -X GET 'https://{api url}/offers/{id}/vouchers/{voucherId}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "sent": "2021-04-06T12:00:00.000Z",
        "contact": "00112233445566778899aabb",
        "channel": "00112233445566778899aabb",
        "recipient": "00112233445566778899aabb",
        "formSubmission": "00112233445566778899aabb",
        "redeemed": {
            "on": "2021-04-06T12:00:00.000Z"
        },
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "voucher"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer
_voucherId ID Unique identifier of the voucher

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher

PUT /offers/:_id/vouchers/:_voucherId

Update a specific offer in an account

Request

$ curl -X PUT 'https://{api url}/offers/{id}/vouchers/{voucherId}' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"
      -d '
          {
              "data": {
                  "name": "Offer 1",
                  "description": "Offer 1 description",
                  "externalId": "",
                  "controller": "",
                  "rules": {
                      "startDatetime": "2021-04-06T12:00:00.000Z",
                      "endDatetime": "2021-04-06T12:00:00.000Z",
                      "voucherLifetime": 1,
                      "maximumVouchers": 1
                  }
              }
          }
      '

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "name": "Offer 1",
        "description": "Offer 1 description",
        "externalId": "",
        "controller": "contacta",
        "account": "00112233445566778899aabb",
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "rules": {
            "startDatetime": "2021-04-06T12:00:00.000Z",
            "endDatetime": "2021-04-06T12:00:00.000Z",
            "voucherLifetime": 1,
            "maximumVouchers": 1
        }
    },
    "meta": {
        "type": "offer"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer
_voucherId ID Unique identifier of the voucher

Body Parameters

Attribute Type Description
code String (Optional) The unique voucher code
expiryDatetime ISO Date (Optional) Voucher expiry datetime
contact ID (Optional) Reference to contact
redeemed.on ISO Date (Optional) Redeemed datetime

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher

GET /offers/:_id/vouchers/:_voucherId/redeemable

Check if a voucher is redeemable by voucherId

Request

$ curl -X GET 'https://{api url}/offers/{id}/vouchers/{voucherId}/redeemable' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "sent": "2021-04-06T12:00:00.000Z",
        "contact": "00112233445566778899aabb",
        "channel": "00112233445566778899aabb",
        "recipient": "00112233445566778899aabb",
        "formSubmission": "00112233445566778899aabb",
        "redeemed": {
            "on": "2021-04-06T12:00:00.000Z"
        },
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "redeemable": false
    },
    "meta": {
        "type": "voucher"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer
_voucherId ID Unique identifier of the voucher

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher
redeemable Boolean Whether this voucher is redeemable

GET /offers/:_id/vouchers/:_voucherCode/redeemable

Check if a voucher is redeemable by voucherCode

Request

$ curl -X GET 'https://{api url}/offers/{id}/vouchers/{voucherCode}/redeemable' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "sent": "2021-04-06T12:00:00.000Z",
        "contact": "00112233445566778899aabb",
        "channel": "00112233445566778899aabb",
        "recipient": "00112233445566778899aabb",
        "formSubmission": "00112233445566778899aabb",
        "redeemed": {
            "on": "2021-04-06T12:00:00.000Z"
        },
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb",
        "redeemable": false
    },
    "meta": {
        "type": "voucher"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer
_voucherCode ID The unique voucher code of the offer

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher
redeemable Boolean Whether this voucher is redeemable

GET /vouchers/:_voucherCode/redeemable

Retrieve a list of vouchers with a voucher code in the account

Request

$ curl -X GET 'https://{api url}/vouchers/{voucherCode}/redeemable' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "items": [
        {
            "data": {
                "_id": "00112233445566778899aabb",
                "code": "0000",
                "account": "00112233445566778899aabb",
                "expiryDatetime": "2021-04-06T12:00:00.000Z",
                "offer": "00112233445566778899aabb",
                "sent": "2021-04-06T12:00:00.000Z",
                "contact": "00112233445566778899aabb",
                "channel": "00112233445566778899aabb",
                "recipient": "00112233445566778899aabb",
                "formSubmission": "00112233445566778899aabb",
                "redeemed": {
                    "on": "2021-04-06T12:00:00.000Z"
                },
                "created": "2021-04-06T12:00:00.000Z",
                "createdBy": "00112233445566778899aabb",
                "modified": "2021-04-06T12:00:00.000Z",
                "modifiedBy": "00112233445566778899aabb",
                "redeemable": false
            },
            "meta": {
                "type": "voucher"
            }
        }
    ],
    "meta": {
        "type": "collection",
        "count": 1,
        "links": {
            "self": "/vouchers/0000/redeemable"
        }
    }
}

Path Parameters

Attribute Type Description
_voucherCode ID The unique voucher code

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher
redeemable Boolean Whether this voucher is redeemable

GET /offers/:_id/vouchers/:_voucherId/redeem

Redeem a voucher by the voucherId

Request

$ curl -X GET 'https://{api url}/offers/{id}/vouchers/{voucherId}/redeem' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "sent": "2021-04-06T12:00:00.000Z",
        "contact": "00112233445566778899aabb",
        "channel": "00112233445566778899aabb",
        "recipient": "00112233445566778899aabb",
        "formSubmission": "00112233445566778899aabb",
        "redeemed": {
            "on": "2021-04-06T12:00:00.000Z"
        },
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "voucher"
    }
}

Path Parameters

Attribute Type Description
_id ID Unique identifier of the offer
_voucherId ID Unique identifier of the voucher

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher

GET /vouchers/:_voucherCode/redeem

Redeem a voucher by the voucherCode

Request

$ curl -X GET 'https://{api url}/vouchers/{voucherCode}/redeem' \
      -H "Authorization: Bearer {token}" \
      -H "Timestamp: {timestamp}" \
      -H "Content-Type: application/json"

Response

HTTP/1.1 200

{
    "data": {
        "_id": "00112233445566778899aabb",
        "code": "0000",
        "account": "00112233445566778899aabb",
        "expiryDatetime": "2021-04-06T12:00:00.000Z",
        "offer": "00112233445566778899aabb",
        "sent": "2021-04-06T12:00:00.000Z",
        "contact": "00112233445566778899aabb",
        "channel": "00112233445566778899aabb",
        "recipient": "00112233445566778899aabb",
        "formSubmission": "00112233445566778899aabb",
        "redeemed": {
            "on": "2021-04-06T12:00:00.000Z"
        },
        "created": "2021-04-06T12:00:00.000Z",
        "createdBy": "00112233445566778899aabb",
        "modified": "2021-04-06T12:00:00.000Z",
        "modifiedBy": "00112233445566778899aabb"
    },
    "meta": {
        "type": "voucher"
    }
}

Path Parameters

Attribute Type Description
_voucherCode ID The unique voucher code

Response

Attribute Type Description
_id ID Unique identifier of the voucher
code String The unique voucher code
account ID Account the voucher belongs to
expiryDatetime ISO Date Voucher expiry datetime
offer ID Reference to voucher offer
sent ISO Date Datetime voucher was assigned to a user
contact ID Reference to contact
channel ID Reference to campaign channel
recipient ID Reference to campaign recipient
formSubmission ID Reference to form submission
redeemed.on ISO Date Redeemed datetime
created ISO Date When the voucher was created
createdBy ID Who created the voucher
modified ISO Date When the voucher was last modified
modifiedBy ID Who last modified the voucher