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
- Learn about common format of API requests, responses and errors.
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
{whitelabel}is the subdomain assigned to the Whitelabel{custom domain}is the domain the Whitelabel owner has chosen to use for their setup
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.
:ascto sort by ascending value:descto sort by descending value
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 |
Meta's Links Attributes
| 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.
- By Account
- You can make up to 3,600 requests per hour.
- By IP
- You can make up to 150 requests per minute.
- You can make up to 30 requests in 10 seconds.
If your limit reaches zero, subsequent requests will receive the 429 Too Many Requests
If you are consistently running into the current limits, please consider retrying the requests based on an exponential backoff strategy.
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:
- Resource owner - Any end-user within your account, who is capable of granting protected resource access to the client.
- Protected resource - Information beng accessed, e.g. accounts, contacts, transactions etc.
- Resource servers - The server hosting the protected resources. In this case the Sprout servers.
- Client - An application that makes protected resource requests to resource servers on your behalf, e.g. a server or a browser.
- Authorisation server - The server that issues tokens to the client. In this case, the Sprout servers.
- Access Token - Credentials provided by the authorisation server that provide access to protected resources.
- Refresh Token - Credentials used to obtain a new access token when the current access token expires.
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:
- Authorisation Code Grant - Use this flow if you want to authorise a client.
- Refresh Token Grant - Use this flow to renew an access token when the current one expires.
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:
response_type- Must be set tocodeclient_id- The same unique identifier of the client you received from registrationredirect_uri- The same URL you registered as Callback URL during client registrationstate- (optional) - A string used to maintain the state between the request and callback
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 |
| 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 |
| 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 |
| 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 |
|---|---|---|
| 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 |
| 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 |
| 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 |
|---|---|---|
| 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 |
| 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 |
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 | 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",
"alias": "abc@test.com"
"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 |
| contactId | ID | Reference to the contact the recipient belongs to |
| alias | String | Address the message is sent to. Could be email/mobile/deviceId |
| 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 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 |
GET /templates/styles
Retrieve a list of template styles for a specific account where the content is not free-style
Request
$ curl -X GET 'https://{api url}/templates/styles' \
-H "Authorization: Bearer {token}" \
-H "Timestamp: {timestamp}" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200
{
"items": [
{
"data": {
"_id": "66ea48f4c0248bf835504c23",
"name": "New Product Launch",
"subject": "Introducing Our Latest Product!",
"language": "",
"featured": false,
"notification": false,
"sharedAccounts": [],
"tags": [
"Marketing",
"Product Launch",
"Q4 Campaign"
],
"account": "5b0e58bd101bf42c926a2129",
"content": {
"styles": {
"text": {
"text_font": "Helvetica, Arial, sans-serif",
"text_size": "16px",
"text_color": "#878b8b",
"line_height": "25px"
},
"heading": {
"line_height": "31px"
},
"links": {
"text_color": "#4372A8",
"underline": true,
"font_weight": "normal"
},
"email_content": {
"width": "600px",
"background_color": "#FFFFFF",
"border_type": "solid",
"border_color": "#FFFFFF",
"border_thickness": "0px"
},
"email_body": {
"background_color": "#282d5a",
"background_image": "https://images.unsplash.com/photo-1719937206158-cad5e6775044?q=80&w=2070&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDF8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
"background_size": "auto",
"border_type": "solid",
"border_color": "#FFFFFF",
"border_thickness": "10px"
}
},
"autosave": true,
"createdAt": "2024-10-03T04:40:13.247Z",
"createdBy": "666f88d94efc4a54ad562a39"
},
"modifiedBy": "573055cb353daeec26f5ee3b",
"createdBy": "666f88d94efc4a54ad562a39"
},
"meta": {
"type": "template"
}
}
],
"meta": {
"type": "collection",
"count": 1,
"links": {
"totalPage": 1,
"self": "/templates/styles?pageSize=50&page=1",
"firstPage": "/templates/styles?pageSize=50&page=1",
"lastPage": "/templates/styles?pageSize=50&page=1"
}
}
}
Response
| Attribute | Type | Description |
|---|---|---|
| _id | ID | Unique identifier of the template |
| name | String | Name of the email template |
| subject | String | Subject of the email template |
| language | String | Language of the email template (currently not set) |
| featured | Boolean | Whether the template is featured |
| notification | Boolean | Whether the template is used for notifications |
| sharedAccounts | Array of IDs | List of accounts that share this template |
| tags | Array of Strings | Tags assigned to the template for categorization |
| account | ID | ID of the account the template belongs to |
| content.styles.text.text_font | String | Font of the email text |
| content.styles.text.text_size | String | Size of the email text |
| content.styles.text.text_color | String | Color of the email text |
| content.styles.text.line_height | String | Line height of the email text |
| content.styles.heading.line_height | String | Line height of the heading |
| content.styles.links.text_color | String | Color of the links in the email |
| content.styles.links.underline | Boolean | Whether links are underlined |
| content.styles.links.font_weight | String | Font weight of the links |
| content.styles.email_content.width | String | Width of the email content container |
| content.styles.email_content.background_color | String | Background color of the email content |
| content.styles.email_content.border_type | String | Border type of the email content container |
| content.styles.email_content.border_color | String | Border color of the email content |
| content.styles.email_content.border_thickness | String | Border thickness of the email content container |
| content.styles.email_body.background_color | String | Background color of the email body |
| content.styles.email_body.background_image | URL | Background image URL for the email body |
| content.styles.email_body.background_size | String | Size of the background image |
| content.styles.email_body.border_type | String | Border type of the email body |
| content.styles.email_body.border_color | String | Border color of the email body |
| content.styles.email_body.border_thickness | String | Border thickness of the email body |
| autosave | Boolean | Whether the template is autosaved |
| createdAt | ISO Date | Date and time when the template was created |
| createdBy | ID | ID of the user that created the template |
| modifiedBy | ID | ID of the user that last modified the template |
PUT /templates/:_id/styles
Update template styles for a specific account where the content is not free-style
Request
$ curl -X PUT 'https://{api url}/templates/{id}/styles' \
-H "Authorization: Bearer {token}" \
-H "Timestamp: {timestamp}" \
-H "Content-Type: application/json"
-d '
{
"data": {
"text": {
"text_font": "Helvetica, Arial, sans-serif",
"text_size": "16px",
"text_color": "#878b8b",
"line_height": "25px"
},
"heading": {
"line_height": "31px"
},
"links": {
"text_color": "#4372A8",
"underline": true,
"font_weight": "normal"
},
"email_content": {
"width": "600px",
"background_color": "#FFFFFF",
"border_type": "solid",
"border_color": "#FFFFFF",
"border_thickness": "0px"
},
"email_body": {
"background_color": "#282d5a",
"background_image": "https://images.unsplash.com/photo-1719937206158-cad5e6775044?q=80&w=2070&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDF8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
"background_size": "auto",
"border_type": "solid",
"border_color": "#FFFFFF",
"border_thickness": "10px"
}
}
}
'
Response
HTTP/1.1 200
{
"data": {
"_id": "66ea48f4c0248bf835504c23",
"deleted": false,
"featured": false,
"notification": false,
"sharedAccounts": [],
"tags": [],
"name": "New Email Template",
"subject": "",
"language": "",
"account": "5b0e58bd101bf42c926a2129",
"createdBy": "666f88d94efc4a54ad562a39",
"modifiedBy": "573055cb353daeec26f5ee3b",
"created": "2024-09-18T03:28:52.388Z",
"modified": "2024-10-07T22:50:26.015Z",
"content": {
"_id": "66fe202d8f291566dc3acf97",
"content": "{\"options\":{\"text\":{\"text_font\":\"Helvetica, Arial, sans-serif\",\"text_size\":\"16px\",\"text_color\":\"#878b8b\",\"line_height\":\"25px\"},\"heading\":{\"line_height\":\"31px\"},\"links\":{\"text_color\":\"#4372A8\",\"underline\":true,\"font_weight\":\"normal\"},\"email_content\":{\"width\":\"600px\",\"background_color\":\"#FFFFFF\",\"border_type\":\"solid\",\"border_color\":\"#FFFFFF\",\"border_thickness\":\"0px\"},\"email_body\":{\"background_color\":\"#282d5a\",\"background_image\":\"https://images.unsplash.com/photo-1719937206158-cad5e6775044?q=80&w=2070&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDF8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D\",\"background_size\":\"auto\",\"border_type\":\"solid\",\"border_color\":\"#FFFFFF\",\"border_thickness\":\"10px\"}},\"rows\":[{\"options\":{\"layout\":\"full-width\",\"padding_top\":\"15px\",\"padd,ing_right\":\"0px\",\"padding_bottom\":\"15px\",\"padding_left\":\"0px\",\"bottom_spacing\":\"10px\",\"background_color\":\"\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true,\"top_spacing\":\"30px\"},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"email_header\",\"viewonline_text\":\"view online\",\"preheader_text\":\"\",\"show_preheader\":false,\"styles\":{\"viewonline_text_color\":\"#999999\",\"preheader_text_color\":\"#999999\",\"viewonline_text_size\":\"13px\",\"preheader_text_size\":\"13px\",\"h_align\":\"center\"}}],\"index\":0}],\"index\":0},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"60px\",\"padding_bottom\":\"0px\",\"padding_left\":\"60px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#f7f7f7\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"32.291666666666664%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"0px\"}],\"index\":0},{\"options\":{\"width\":\"35.416666666666664%\"},\"blocks\":[{\"index\":0,\"type\":\"image\",\"image_source\":\"https://stuff.playground.contacta.io/5ab9b88660665542018e3280/files/logo-small2018-11-13T05:52:37.605Z.png\",\"link\":\"\",\"styles\":{\"width\":\"100%\",\"border_radius\":\"0px\",\"border_thickness\":\"0px\",\"border_color\":\"#000000\",\"h_align\":\"center\"},\"bottom_spacing\":\"40px\"}],\"index\":1},{\"options\":{\"width\":\"32.291666666666664%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"0px\"}],\"index\":2}],\"index\":1},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"0px\",\"padding_bottom\":\"0px\",\"padding_left\":\"0px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"image\",\"image_source\":\"https://stuff.playground.contacta.io/5ab9b88660665542018e3280/files/pinapple-banner2018-11-13T05:37:55.011Z.png\",\"link\":\"\",\"styles\":{\"width\":\"100%\",\"border_radius\":\"0px\",\"border_thickness\":\"0px\",\"border_color\":\"#000000\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":2},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"40px\",\"padding_bottom\":\"0px\",\"padding_left\":\"40px\",\"bottom_spacing\":\"60px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"<div style=\\\"text-align: center;\\\"><span style=\\\"font-size:36px;\\\"><span style=\\\"font-family:Trebuchet MS,Helvetica,sans-serif;\\\">A slice just for you</span></span></div>\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"30px\"},{\"index\":1,\"type\":\"text\",\"content\":\"<div style=\\\"text-align: center;\\\">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. </div>\",\"bottom_spacing\":\"35px\"},{\"index\":2,\"type\":\"button\",\"text\":\"Check it out\",\"link\":\"#\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"18px\",\"text_color\":\"#ffffff\",\"background_color\":\"#bac1c9\",\"border_radius\":\"5px\",\"width\":\"165px\",\"height\":\"57px\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":3},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"0px\",\"padding_bottom\":\"0px\",\"padding_left\":\"0px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"image\",\"image_source\":\"https://stuff.playground.contacta.io/5ab9b88660665542018e3280/files/banana-long2018-11-08T06:20:24.250Z.png\",\"link\":\"\",\"styles\":{\"width\":\"100%\",\"border_radius\":\"0px\",\"border_thickness\":\"0px\",\"border_color\":\"#000000\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":4},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"40px\",\"padding_bottom\":\"0px\",\"padding_left\":\"40px\",\"bottom_spacing\":\"60px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"<div style=\\\"text-align: center;\\\"><span style=\\\"font-size:36px;\\\"><span style=\\\"font-family:Trebuchet MS,Helvetica,sans-serif;\\\">Peel the banana</span></span></div>\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"30px\"},{\"index\":1,\"type\":\"text\",\"content\":\"<div style=\\\"text-align: center;\\\">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</div>\",\"bottom_spacing\":\"35px\"},{\"index\":2,\"type\":\"button\",\"text\":\"Do it now\",\"link\":\"#\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"18px\",\"text_color\":\"#ffffff\",\"background_color\":\"#bac1c9\",\"border_radius\":\"5px\",\"width\":\"165px\",\"height\":\"57px\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":5},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"0px\",\"padding_bottom\":\"0px\",\"padding_left\":\"0px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"image\",\"image_source\":\"https://stuff.playground.contacta.io/5ab9b88660665542018e3280/files/watermelon2018-11-08T07:00:14.020Z.png\",\"link\":\"\",\"styles\":{\"width\":\"100%\",\"border_radius\":\"0px\",\"border_thickness\":\"0px\",\"border_color\":\"#000000\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":6},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"40px\",\"padding_bottom\":\"0px\",\"padding_left\":\"40px\",\"bottom_spacing\":\"60px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"<div style=\\\"text-align: center;\\\"><span style=\\\"font-size:36px;\\\"><span style=\\\"font-family:Trebuchet MS,Helvetica,sans-serif;\\\">Stick the watermelon</span></span></div>\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"30px\"},{\"index\":1,\"type\":\"text\",\"content\":\"<div style=\\\"text-align: center;\\\">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. </div>\",\"bottom_spacing\":\"35px\"},{\"index\":2,\"type\":\"button\",\"text\":\"Take a bite\",\"link\":\"#\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"18px\",\"text_color\":\"#ffffff\",\"background_color\":\"#bac1c9\",\"border_radius\":\"5px\",\"width\":\"165px\",\"height\":\"57px\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":7},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"0px\",\"padding_bottom\":\"0px\",\"padding_left\":\"0px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"image\",\"image_source\":\"https://stuff.playground.contacta.io/5ab9b88660665542018e3280/files/lemon-long2018-11-08T06:20:32.397Z.png\",\"link\":\"\",\"styles\":{\"width\":\"100%\",\"border_radius\":\"0px\",\"border_thickness\":\"0px\",\"border_color\":\"#000000\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":8},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"40px\",\"padding_bottom\":\"0px\",\"padding_left\":\"40px\",\"bottom_spacing\":\"60px\",\"background_color\":\"#ffffff\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"heading\",\"content\":\"<div style=\\\"text-align: center;\\\"><span style=\\\"font-size:36px;\\\"><span style=\\\"font-family:Trebuchet MS,Helvetica,sans-serif;\\\">Squeeze the lemon</span></span></div>\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"26px\",\"text_color\":\"#000000\"},\"bottom_spacing\":\"30px\"},{\"index\":1,\"type\":\"text\",\"content\":\"<div style=\\\"text-align: center;\\\">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum</div>\",\"bottom_spacing\":\"35px\"},{\"index\":2,\"type\":\"button\",\"text\":\"Slice it now\",\"link\":\"#\",\"styles\":{\"text_font\":\"Arial, Helvetica, sans-serif\",\"text_size\":\"18px\",\"text_color\":\"#ffffff\",\"background_color\":\"#bac1c9\",\"border_radius\":\"5px\",\"width\":\"165px\",\"height\":\"57px\",\"h_align\":\"center\"},\"bottom_spacing\":\"50px\"}],\"index\":0}],\"index\":9},{\"options\":{\"layout\":\"joined\",\"padding_top\":\"0px\",\"padding_right\":\"30px\",\"padding_bottom\":\"0px\",\"padding_left\":\"30px\",\"bottom_spacing\":\"0px\",\"background_color\":\"#f7f7f7\",\"background_image\":\"\",\"background_size\":\"auto\",\"mobile_responsive\":true},\"columns\":[{\"options\":{\"width\":\"100%\"},\"blocks\":[{\"index\":0,\"type\":\"email_footer\",\"logo_image_source\":\"https://stuff.playground.contacta.io/5ab870af9abc0b62c00e612a/files/Connectlogo120221102T2117012023-05-01T04%3A19%3A18.318Z.png\",\"show_forward_to_friend\":true,\"styles\":{\"logo_size\":\"none\",\"text_size\":\"12px\",\"text_color\":\"#404040\"},\"bottom_spacing\":\"50px\",\"email_forward_text\":\"Forward to a Friend\",\"contact_email_label\":\"This email was sent to\",\"unsubscribe_text\":\"Unsubscribe\",\"unsubscribe_link\":\"{email.unsubscribe}\",\"whitelabel_text\":\"Powered By\"}],\"index\":0}],\"index\":10}]}",
"freeStyle": false,
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
},
"thumbnailURL": "https://stuff.playground.contacta.io/5b0e58bd101bf42c926a2129/thumbnails/template66ea48f4c0248bf835504c232024-10-07T22%3A50%3A25.806Z.png"
},
"meta": {
"type": "template"
}
}
Path Parameters
| Attribute | Type | Description |
|---|---|---|
| _id | ID | Unique identifier of the template |
Body Parameters
| Attribute | Type | Description |
|---|---|---|
| text | Object | Defines the text styling for the template. |
| text.text_font | String | The font family for the text (e.g., "Helvetica, Arial, sans-serif"). |
| text.text_size | String | The size of the text (e.g., "16px"). |
| text.text_color | String | The color of the text in hex format (e.g., "#878b8b"). |
| text.line_height | String | The line height for the text (e.g., "25px"). |
| heading | Object | Defines the heading styling for the template. |
| heading.line_height | String | The line height for the heading (e.g., "31px"). |
| links | Object | Defines the link styling for the template. |
| links.text_color | String | The color of the links in hex format (e.g., "#4372A8"). |
| links.underline | Boolean | Indicates whether the links should be underlined (e.g., true). |
| links.font_weight | String | The font weight for the links (e.g., "normal"). |
| email_content | Object | Defines the content styling for the email. |
| email_content.width | String | The width of the email content (e.g., "600px"). |
| email_content.background_color | String | The background color for the email content in hex format (e.g., "#FFFFFF"). |
| email_content.border_type | String | The type of border (e.g., "solid"). |
| email_content.border_color | String | The border color in hex format (e.g., "#FFFFFF"). |
| email_content.border_thickness | String | The thickness of the border (e.g., "0px"). |
| email_body | Object | Defines the body styling for the email. |
| email_body.background_color | String | The background color for the email body in hex format (e.g., "#282d5a"). |
| email_body.background_image | String | The URL for the background image of the email body. |
| email_body.background_size | String | The size of the background image (e.g., "auto"). |
| email_body.border_type | String | The type of border for the email body (e.g., "solid"). |
| email_body.border_color | String | The border color in hex format (e.g., "#FFFFFF"). |
| email_body.border_thickness | String | The thickness of the border for the email body (e.g., "10px"). |
Response
| Attribute | Type | Description |
|---|---|---|
| _id | ID | Unique identifier of the template |
| deleted | Boolean | Whether the template has been deleted or not |
| featured | Boolean | Whether the template is featured or not |
| notification | Boolean | Whether the template has notifications enabled or not |
| sharedAccounts | Array of Strings | List of shared account IDs associated with the template |
| tags | Array of Strings | Tags assigned to the template for categorization |
| name | String | Name of the template |
| subject | String | Subject line of the template |
| language | String | Language of the template |
| account | ID | Reference to the account the template belongs to |
| createdBy | ID | ID of the user that created the template |
| modifiedBy | ID | ID of the user that last modified the template |
| created | ISO Date | Date and time when the template was created |
| modified | ISO Date | Date and time when the template was last modified |
| content | Object | Contains details of the template's content |
| content._id | ID | Unique identifier of the content |
| content.content | String | Styles provided in JSON stringified format |
| content.freeStyle | Boolean | Whether the template is in free style mode or not |
| content.userAgent | String | User agent string from which the template was created |
| thumbnailURL | String | URL of the template thumbnail |
GET /visits
Retrieve visits/bookings by Account
Request
$ curl -X GET 'https://{api url}/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": "/visits"
}
}
}
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 |
GET /transactions
Retrieve a list of transactions by Account
Request
$ curl -X GET 'https://{api url}/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": "/transactions"
}
}
}
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 |