The Contacts Management API provides the necessary endpoints to manage your contacts.

Overview

The API provides access to two main resources:

Contacts: Data associated with the individuals you need to contact.
Lists: Groups of contacts created for specific purposes.

Base URI

The API uses the following base URI:

https://api.etxtservice.co.nz/

Authentication

All requests to the Contacts REST API must be authenticated, this can either be done using Basic Authentication or by signing with a HMAC signature.

Basic Authentication

Every request requires an Authorization header in the following format:

Authorization: Basic Base64(api_key:api_secret)

Where the header consists of the Basic keyword followed by your Basic Authentication api_key and api_secret that you have been supplied by support, seperated with a colon (:) which is then Base64 encoded.

Example request with Basic Authentication

POST /api/v1/contacts/contacts HTTP/1.1
Host: api.etxtservice.co.nz
Accept: application/json
Content-Type: application/json
Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp
        {
          "firstName": "Adam",
          "lastName": "Smith",
          "channels": [
            {
              "channelId": "+15553456783",
              "type": "PHONE",
              "subscriptionState": "UNSUBSCRIBED"
            }
          ],
          "lists": [
            {
              "name": "My group",
              "alias": "Group1"
            }
          ],
          "customFields": [
            {
              "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
              "value": "John"
            }
        }

Note: spaces are used as indentation in the body of the above request.

HMAC Authentication

Every request requires an Authorization header in the following formats:

For a request with a request body:

Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="<SIGNATURE>"

For a request without a request body:

Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date request-line", signature="<SIGNATURE>"

To create this header

Step 1

Add a Date header to the request using the current date time in RFC7231 Section 7.1.1.2 format

Step 2

If the request has a body, add a header called Content-MD5 where the value of this header is an MD5 hash of the request body, otherwise this header is not required

Step 3

Create a signing string by concatenating the Date header, the Content-MD5 header (if set) and the request line with line breaks:

Date: Sat, 30 Jul 2016 05:13:23 GMT\nContent-MD5: 10fd4feab20d38432480c07301e49616\nPOST /api/v1/contacts HTTP/1.1

Date: Sat, 30 Jul 2016 05:13:23 GMT\nGET /api/v1/contacts/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1

Step 4

Create a SHA1 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8) HMAC-SHA1(signing string, secret)

Step 5

Base64 encode the HMAC hash and include it as the signature in the Authorization header

Example request with body

POST /api/v1/contacts HTTP/1.1
Host: api.etxtservice.co.nz
Accept: application/json
Content-Type: application/json
Date: Sat, 30 Jul 2016 05:18:52 GMT
Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA="
Content-MD5: 5407644fa83bec240dede971307e0cad
Content-Length: 133
{
  // Payload
}

Note: spaces are used as indentation in the body of the above request.

Example request without body

POST /api/v1/contacts HTTP/1.1
Host: api.etxtservice.co.nz
Accept: application/json
Date: Sat, 30 Jul 2016 05:18:52 GMT
Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date request-line", signature="NTUwMjUwNTVmZGYzZTIxODMyYjc1ZmM3M2EwZWQ1NzA3NzA4ZTZjNw=="
Content-Length: 133
{
  // Payload
}

Contacts
Lists
Custom Fields

Contacts

Contacts resources.

Retrieve Contacts

GET /api/v1/contacts/contacts

Retrieve contacts based on the filter. If there is no filter, then it will return the next page sorted by creationDate

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`nextPageToken`	query	string	No	Token to retrieve the next page of results.
`prevPageToken`	query	string	No	Token to retrieve the previous page of results.
`pageSize`	query	integer	No	Number of results per page. Defaults to 1000.
`listIds`	query	string	No	Filter results by specific list IDs.
`contactIds`	query	string	No	Filter results by specific contact IDs.
`channelIds`	query	string	No	Filter results by specific channel IDs.
`channelTypes`	query	string	No	Filter results by channel types. + Enum: `PHONE`, `SMS`, `EMAIL`
`channelSubscriptionState`	query	string	No	Filter results by subscription state. + Enum: `SUBSCRIBED`, `UNSUBSCRIBED`
`query`	query	string	No	Free-text search across contact name, email, custom fields and channel identifiers.

Responses

200 — Returns a contacts page

Field	Type	Required	Description
`content`	array of object	Yes	Page content and number of elements is restricted by page size
`content[].id`	string	Yes	Contact id in UUID format
`content[].accountId`	string	Yes	Account id
`content[].vendorId`	string	Yes	Vendor id
`content[].firstName`	string	Yes	Contact first name
`content[].lastName`	string	Yes	Contact last name
`content[].fullName`	string	Yes	Contact full name
`content[].alias`	string	Yes	Contact alias
`content[].dateOfBirth`	string	No	Date of birth
`content[].country`	string	Yes	Country
`content[].state`	string	Yes	State
`content[].location`	string	Yes	Location
`content[].note`	string	Yes	Note
`content[].createdDate`	string	Yes	Create date
`content[].lastModifiedDate`	string	Yes	Last modified date
`content[].customFields`	array of object	Yes	List of custom fields
`content[].customFields[].id`	string	Yes	Custom Field id in UUID format
`content[].customFields[].mergeTag`	string	Yes	Custom field merge tag
`content[].customFields[].value`	string	Yes	Custom field value
`content[].customFields[].type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`content[].channels`	array of object	Yes	Contact channels
`content[].channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`content[].channels[].type`	enum: SMS, WHATSAPP, GBM, INSTAGRAM, FACEBOOK, EMAIL	Yes	Contact channel type
`content[].channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`content[].lists`	array of object	Yes	Contact lists
`content[].lists[].id`	string	Yes	List id in UUID format
`content[].lists[].name`	string	Yes	List name
`nextPageToken`	string	No	Pagination token to retrieve the next page
`prevPageToken`	string	No	Pagination token to retrieve the previous page
`totalElements`	integer	Yes	Total number of elements

Example:

{
  "content": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "accountId": "string",
      "vendorId": "string",
      "firstName": "Adam",
      "lastName": "Smith",
      "fullName": "Adam Smith",
      "alias": "VIP contact",
      "dateOfBirth": "2022-08-18",
      "country": "US",
      "state": "CA",
      "location": "Sunset Blvd",
      "note": "Note",
      "createdDate": "2022-08-18T09:15:03.112Z",
      "lastModifiedDate": "2022-08-18T09:15:03.112Z",
      "customFields": [
        {
          "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
          "mergeTag": "contact_name",
          "value": "John",
          "type": "DATE"
        }
      ],
      "channels": [
        {
          "channelId": "+15553456783",
          "type": "SMS",
          "subscriptionState": "UNSUBSCRIBED"
        }
      ],
      "lists": [
        {
          "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
          "name": "My list"
        }
      ]
    }
  ],
  "nextPageToken": "string",
  "prevPageToken": "string",
  "totalElements": 25
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/contacts?nextPageToken=abc123&prevPageToken=xyz456&pageSize=1000&listIds=3fa85f64-5717-4562-b3fc-2c963f66afa6&contactIds=3fa85f64-5717-4562-b3fc-2c963f66afa6&channelIds=%2B15556667777&channelTypes=PHONE%2CSMS&channelSubscriptionState=SUBSCRIBED&query=john" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Create Contact

POST /api/v1/contacts/contacts

Create a new contact using the specified parameters. If one or more lists are provided, the contact will be assigned to them. If the contact is created with a SUBSCRIBED status but was previously UNSUBSCRIBED, the contact will be created as UNSUBSCRIBED. However, the contact can be re-subscribed later if needed.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
`firstName`	string	No	Contact first name
`lastName`	string	No	Contact last name
`alias`	string	No	Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms
`dateOfBirth`	string	No	Date of birth
`country`	string	No	Country
`state`	string	No	State
`location`	string	No	Location
`note`	string	No	Note
`channels`	array of object	Yes	Contact channels
`channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`channels[].type`	enum: SMS, WHATSAPP	Yes	Contact channel type
`channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`lists`	array of object	No	Contact lists
`lists[].id`	string	Yes	List id in UUID format
`customFields`	array of object	No	Contact custom fields
`customFields[].id`	string	Yes	Custom Field id in UUID format
`customFields[].value`	string	Yes	Custom field value

Example

{
  "firstName": "Adam",
  "lastName": "Smith",
  "alias": "user1234",
  "dateOfBirth": "2022-08-18",
  "country": "US",
  "state": "CA",
  "location": "Sunset Blvd",
  "note": "Note",
  "channels": [
    {
      "channelId": "+15553456783",
      "type": "SMS",
      "subscriptionState": "UNSUBSCRIBED"
    }
  ],
  "lists": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee"
    }
  ],
  "customFields": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "value": "John"
    }
  ]
}

Responses

201 — Contact succesfully created

Field	Type	Required	Description
`id`	string	Yes	Contact id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`firstName`	string	Yes	Contact first name
`lastName`	string	Yes	Contact last name
`fullName`	string	Yes	Contact full name
`alias`	string	Yes	Contact alias
`dateOfBirth`	string	No	Date of birth
`country`	string	Yes	Country
`state`	string	Yes	State
`location`	string	Yes	Location
`note`	string	Yes	Note
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date
`customFields`	array of object	Yes	List of custom fields
`customFields[].id`	string	Yes	Custom Field id in UUID format
`customFields[].mergeTag`	string	Yes	Custom field merge tag
`customFields[].value`	string	Yes	Custom field value
`customFields[].type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`channels`	array of object	Yes	Contact channels
`channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`channels[].type`	enum: SMS, WHATSAPP, GBM, INSTAGRAM, FACEBOOK, EMAIL	Yes	Contact channel type
`channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`lists`	array of object	Yes	Contact lists
`lists[].id`	string	Yes	List id in UUID format
`lists[].name`	string	Yes	List name

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "firstName": "Adam",
  "lastName": "Smith",
  "fullName": "Adam Smith",
  "alias": "VIP contact",
  "dateOfBirth": "2022-08-18",
  "country": "US",
  "state": "CA",
  "location": "Sunset Blvd",
  "note": "Note",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z",
  "customFields": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "mergeTag": "contact_name",
      "value": "John",
      "type": "DATE"
    }
  ],
  "channels": [
    {
      "channelId": "+15553456783",
      "type": "SMS",
      "subscriptionState": "UNSUBSCRIBED"
    }
  ],
  "lists": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "name": "My list"
    }
  ]
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The contact already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X POST "https://api.etxtservice.co.nz/api/v1/contacts/contacts" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Adam","lastName":"Smith","alias":"user1234","dateOfBirth":"2022-08-18","country":"US","state":"CA","location":"Sunset Blvd","note":"Note","channels":[{"channelId":"+15553456783","type":"SMS","subscriptionState":"UNSUBSCRIBED"}],"lists":[{"id":"025e93d3-051b-43f9-b12e-4b5842228dee"}],"customFields":[{"id":"025e93d3-051b-43f9-b12e-4b5842228dee","value":"John"}]}'

Get Contact

GET /api/v1/contacts/contacts/{contactId}

Retrieve a contact based on the contactId. ContactId is unique.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`contactId`	path	string	Yes	The unique identifier for a contact in UUID format

Responses

200 — Contact requested data

Field	Type	Required	Description
`id`	string	Yes	Contact id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`firstName`	string	Yes	Contact first name
`lastName`	string	Yes	Contact last name
`fullName`	string	Yes	Contact full name
`alias`	string	Yes	Contact alias
`dateOfBirth`	string	No	Date of birth
`country`	string	Yes	Country
`state`	string	Yes	State
`location`	string	Yes	Location
`note`	string	Yes	Note
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date
`customFields`	array of object	Yes	List of custom fields
`customFields[].id`	string	Yes	Custom Field id in UUID format
`customFields[].mergeTag`	string	Yes	Custom field merge tag
`customFields[].value`	string	Yes	Custom field value
`customFields[].type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`channels`	array of object	Yes	Contact channels
`channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`channels[].type`	enum: SMS, WHATSAPP, GBM, INSTAGRAM, FACEBOOK, EMAIL	Yes	Contact channel type
`channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`lists`	array of object	Yes	Contact lists
`lists[].id`	string	Yes	List id in UUID format

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "firstName": "Adam",
  "lastName": "Smith",
  "fullName": "Adam Smith",
  "alias": "VIP contact",
  "dateOfBirth": "2022-08-18",
  "country": "US",
  "state": "CA",
  "location": "Sunset Blvd",
  "note": "Note",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z",
  "customFields": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "mergeTag": "contact_name",
      "value": "John",
      "type": "DATE"
    }
  ],
  "channels": [
    {
      "channelId": "+15553456783",
      "type": "SMS",
      "subscriptionState": "UNSUBSCRIBED"
    }
  ],
  "lists": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee"
    }
  ]
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Delete Contact

DELETE /api/v1/contacts/contacts/{contactIdToDelete}

Delete a contact that match with the indicated contact id.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`contactIdToDelete`	path	string	Yes	The unique identifier for a contact in UUID format

Responses

204 — No Content

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X DELETE "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Update Contact

PATCH /api/v1/contacts/contacts/{contactIdToUpdate}

Modify the contact linked to the specified contact ID. Only the fields included in the payload will be updated; all others will remain unchanged. The contact must have at least one communication channel.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`contactIdToUpdate`	path	string	Yes	The unique identifier for a contact in UUID format

Request body

Optional.

Fields

Field	Type	Required	Description
`firstName`	string	No	Contact first name
`lastName`	string	No	Contact last name
`alias`	string	No	Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms
`dateOfBirth`	string	No	Date of birth
`country`	string	No	Country
`state`	string	No	State
`location`	string	No	Location
`note`	string	No	Note
`channels`	array of object	No	Contact channels
`channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`channels[].type`	enum: SMS, WHATSAPP, GBM, INSTAGRAM, FACEBOOK, EMAIL	Yes	Contact channel type
`channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`lists`	array of object	No	Contact lists
`lists[].id`	string	Yes	List id in UUID format
`customFields`	array of object	No	Contact custom fields
`customFields[].id`	string	Yes	Custom Field id in UUID format
`customFields[].value`	string	Yes	Custom field value

Example

{
  "firstName": "Adam",
  "lastName": "Smith",
  "alias": "user1234",
  "dateOfBirth": "2022-08-18",
  "country": "US",
  "state": "CA",
  "location": "Sunset Blvd",
  "note": "Note",
  "channels": [
    {
      "channelId": "+15553456783",
      "type": "SMS",
      "subscriptionState": "UNSUBSCRIBED"
    }
  ],
  "lists": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee"
    }
  ],
  "customFields": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "value": "John"
    }
  ]
}

Responses

200 — Contact updated

Field	Type	Required	Description
`id`	string	Yes	Contact id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`firstName`	string	Yes	Contact first name
`lastName`	string	Yes	Contact last name
`fullName`	string	Yes	Contact full name
`alias`	string	Yes	Contact alias
`dateOfBirth`	string	No	Date of birth
`country`	string	Yes	Country
`state`	string	Yes	State
`location`	string	Yes	Location
`note`	string	Yes	Note
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date
`customFields`	array of object	Yes	List of custom fields
`customFields[].id`	string	Yes	Custom Field id in UUID format
`customFields[].mergeTag`	string	Yes	Custom field merge tag
`customFields[].value`	string	Yes	Custom field value
`customFields[].type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`channels`	array of object	Yes	Contact channels
`channels[].channelId`	string	Yes	Contact channel id (in case phone number - in E164 international format)
`channels[].type`	enum: SMS, WHATSAPP, GBM, INSTAGRAM, FACEBOOK, EMAIL	Yes	Contact channel type
`channels[].subscriptionState`	enum: SUBSCRIBED, UNSUBSCRIBED	No	Subscription state
`lists`	array of object	Yes	Contact lists
`lists[].id`	string	Yes	List id in UUID format
`lists[].name`	string	Yes	List name

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "firstName": "Adam",
  "lastName": "Smith",
  "fullName": "Adam Smith",
  "alias": "VIP contact",
  "dateOfBirth": "2022-08-18",
  "country": "US",
  "state": "CA",
  "location": "Sunset Blvd",
  "note": "Note",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z",
  "customFields": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "mergeTag": "contact_name",
      "value": "John",
      "type": "DATE"
    }
  ],
  "channels": [
    {
      "channelId": "+15553456783",
      "type": "SMS",
      "subscriptionState": "UNSUBSCRIBED"
    }
  ],
  "lists": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "name": "My list"
    }
  ]
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The contact already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X PATCH "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Adam","lastName":"Smith","alias":"user1234","dateOfBirth":"2022-08-18","country":"US","state":"CA","location":"Sunset Blvd","note":"Note","channels":[{"channelId":"+15553456783","type":"SMS","subscriptionState":"UNSUBSCRIBED"}],"lists":[{"id":"025e93d3-051b-43f9-b12e-4b5842228dee"}],"customFields":[{"id":"025e93d3-051b-43f9-b12e-4b5842228dee","value":"John"}]}'

Lists

Lists resources.

Retrieve Lists

GET /api/v1/contacts/lists

Retrieve lists based on the filter. If there is no filter, then it will return the next page sorted by creationDate

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`nextPageToken`	query	string	No	Token to retrieve the next page of results.
`prevPageToken`	query	string	No	Token to retrieve the previous page of results.
`pageSize`	query	integer	No	Number of results per page. Defaults to 1000.
`listIds`	query	string	No	Filter results by specific list IDs.
`alias`	query	string	No	Filter results by list alias.
`name`	query	string	No	Filter results by list name.

Responses

200 — Returns a lists page

Field	Type	Required	Description
`content`	array of object	Yes	Page content and number of elements is restricted by page size
`content[].id`	string	Yes	List id in UUID format
`content[].accountId`	string	Yes	Account id
`content[].vendorId`	string	Yes	Vendor id
`content[].name`	string	Yes	List name
`content[].alias`	string	Yes	List alias
`content[].createdDate`	string	Yes	Create date
`content[].lastModifiedDate`	string	Yes	Last modified date
`nextPageToken`	string	No	Pagination token to retrieve the next page
`prevPageToken`	string	No	Pagination token to retrieve the previous page
`totalElements`	integer	Yes	Total number of elements

Example:

{
  "content": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "accountId": "string",
      "vendorId": "string",
      "name": "My group",
      "alias": "VIP group",
      "createdDate": "2022-08-18T09:15:03.112Z",
      "lastModifiedDate": "2022-08-18T09:15:03.112Z"
    }
  ],
  "nextPageToken": "string",
  "prevPageToken": "string",
  "totalElements": 25
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/lists?nextPageToken=abc123&prevPageToken=xyz456&pageSize=1000&listIds=3fa85f64-5717-4562-b3fc-2c963f66afa6&alias=listAlias&name=listName" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Create List

POST /api/v1/contacts/lists

Create a new contact list.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
`name`	string	Yes	Group name
`alias`	string	No	Group alias

Example

{
  "name": "My group",
  "alias": "Group1"
}

Responses

201 — Contact succesfully created

Field	Type	Required	Description
`id`	string	Yes	List id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`name`	string	Yes	List name
`alias`	string	Yes	List alias
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "name": "My group",
  "alias": "VIP group",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The list already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X POST "https://api.etxtservice.co.nz/api/v1/contacts/lists" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My group","alias":"Group1"}'

Get List

GET /api/v1/contacts/lists/{listId}

Retrieve a list.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listId`	path	string	Yes	The unique identifier for a list in UUID format

Responses

200 — List requested data

Field	Type	Required	Description
`id`	string	Yes	List id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`name`	string	Yes	List name
`alias`	string	Yes	List alias
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "name": "My group",
  "alias": "VIP group",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Delete List

DELETE /api/v1/contacts/lists/{listIdToRemove}

Delete a list that matches with the indicated listId.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listIdToRemove`	path	string	Yes	The unique identifier for a list in UUID format

Responses

204 — No Content

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X DELETE "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Update List

PATCH /api/v1/contacts/lists/{listIdToUpdate}

Modify the list linked to the specified list ID. Only the fields included in the payload will be updated; all others will remain unchanged.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listIdToUpdate`	path	string	Yes	The unique identifier for a list in UUID format

Request body

Optional.

Fields

Field	Type	Required	Description
`name`	string	Yes	Contact list name
`alias`	string	No	Contact list alias
`nameSet`	boolean	No
`aliasSet`	boolean	No

Example

{
  "name": "My list",
  "alias": "List1"
}

Responses

200 — Contact updated

Field	Type	Required	Description
`id`	string	Yes	List id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`name`	string	Yes	List name
`alias`	string	Yes	List alias
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "AccountA",
  "vendorId": "VendorB",
  "name": "My group",
  "alias": "VIP group",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The list already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X PATCH "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My list","alias":"List1"}'

Add Contact to List

POST /api/v1/contacts/lists/{listId}/contacts/{contactToAdd}

Add indicated contact to list.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listId`	path	string	Yes	The unique identifier for a list in UUID format
`contactToAdd`	path	string	Yes	The unique identifier for a contact in UUID format

Responses

200 — Contacts added to the list

Field	Type	Required	Description
`id`	string	Yes	List id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`name`	string	Yes	List name
`alias`	string	Yes	List alias
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "name": "My group",
  "alias": "VIP group",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X POST "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Remove Contact from List

DELETE /api/v1/contacts/lists/{listId}/contacts/{contactId}

One single contact will be removed from the indicated list.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listId`	path	string	Yes	The unique identifier for a list in UUID format
`contactId`	path	string	Yes	The unique identifier for a contact in UUID format

Responses

204 — No Content

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X DELETE "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Add or remove multiple contacts to/from a List

PATCH /api/v1/contacts/lists/{listId}/contacts

Add/Remove indicated contacts to list.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`listId`	path	string	Yes	The unique identifier for a list in UUID format

Request body

Optional.

Fields

Field	Type	Required	Description
`contactsToAddIds`	array of string	No
`contactsToRemoveIds`	array of string	No

Example

{
  "contactsToAddIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "contactsToRemoveIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

Responses

200 — Contacts list updated correctly

Field	Type	Required	Description
`id`	string	Yes	List id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`name`	string	Yes	List name
`alias`	string	Yes	List alias
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "string",
  "vendorId": "string",
  "name": "My group",
  "alias": "VIP group",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X PATCH "https://api.etxtservice.co.nz/api/v1/contacts/lists/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"contactsToAddIds":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"contactsToRemoveIds":["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

Custom Fields

Custom Fields resources.

Retrieve CustomFields

GET /api/v1/contacts/custom-fields

Retrieve customFields based on the filter. If there is no filter, then it will return the next page sorted by creationDate

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`nextPageToken`	query	string	No	Token to retrieve the next page of results.
`prevPageToken`	query	string	No	Token to retrieve the previous page of results.
`pageSize`	query	integer	No	Number of results per page. Defaults to 1000.
`customFieldIds`	query	string	No	Filter results by specific customFields IDs.
`label`	query	string	No	Filter results by custom field label.
`mergeTag`	query	string	No	Filter results by custom field merge tag.

Responses

200 — Returns a CustomField page

Field	Type	Required	Description
`content`	array of object	Yes	Page content and number of elements is restricted by page size
`content[].id`	string	Yes	Custom field id in UUID format
`content[].accountId`	string	Yes	Account id
`content[].vendorId`	string	Yes	Vendor id
`content[].label`	string	Yes	Custom field label
`content[].mergeTag`	string	Yes	Custom field merge tag
`content[].maxLength`	integer	Yes	Custom field max length
`content[].type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`content[].createdDate`	string	Yes	Create date
`content[].lastModifiedDate`	string	Yes	Last modified date
`nextPageToken`	string	No	Pagination token to retrieve the next page
`prevPageToken`	string	No	Pagination token to retrieve the previous page
`totalElements`	integer	Yes	Total number of elements

Example:

{
  "content": [
    {
      "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
      "accountId": "accountId_67846328",
      "vendorId": "string",
      "label": "Contact field new name",
      "mergeTag": "contact_name",
      "maxLength": 50,
      "type": "DATE",
      "createdDate": "2022-08-18T09:15:03.112Z",
      "lastModifiedDate": "2022-08-18T09:15:03.112Z"
    }
  ],
  "nextPageToken": "string",
  "prevPageToken": "string",
  "totalElements": 25
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/custom-fields?nextPageToken=abc123&prevPageToken=xyz456&pageSize=1000&customFieldIds=3fa85f64-5717-4562-b3fc-2c963f66afa6&label=label123&mergeTag=mergeTag345" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Create CustomField

POST /api/v1/contacts/custom-fields

Create a new custom field, which will be linked to the account. This custom field can have a value assigned to it for all contacts within the account.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
`label`	string	Yes	Custom field label
`mergeTag`	string	Yes	Custom field merge tag
`maxLength`	integer	Yes	Custom field max length
`type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type

Example

{
  "label": "Pet name",
  "mergeTag": "pet_name",
  "maxLength": 30,
  "type": "TEXT"
}

Responses

201 — Contact succesfully created

Field	Type	Required	Description
`id`	string	Yes	Custom field id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`label`	string	Yes	Custom field label
`mergeTag`	string	Yes	Custom field merge tag
`maxLength`	integer	Yes	Custom field max length
`type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "accountId_67846328",
  "vendorId": "string",
  "label": "Pet name",
  "mergeTag": "pet_name",
  "maxLength": 30,
  "type": "TEXT",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The contact already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X POST "https://api.etxtservice.co.nz/api/v1/contacts/custom-fields" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"Pet name","mergeTag":"pet_name","maxLength":30,"type":"TEXT"}'

Get CustomField

GET /api/v1/contacts/contacts/{customFieldId}

Retrieve a customField based on the customField id.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`customFieldId`	path	string	Yes	The unique identifier for a customField in UUID format

Responses

200 — Contact requested data

Field	Type	Required	Description
`id`	string	Yes	Custom field id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`label`	string	Yes	Custom field label
`mergeTag`	string	Yes	Custom field merge tag
`maxLength`	integer	Yes	Custom field max length
`type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "accountId_67846328",
  "vendorId": "string",
  "label": "Contact name",
  "mergeTag": "contact_name",
  "maxLength": 30,
  "type": "DATE",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X GET "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Delete CustomField

DELETE /api/v1/contacts/contacts/{customFieldIdToDelete}

Delete a customField that match with the indicated customField id.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`customFieldIdToDelete`	path	string	Yes	The unique identifier for a customField in UUID format

Responses

204 — No Content

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X DELETE "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Update CustomField

PATCH /api/v1/contacts/contacts/{customFieldIdToUpdate}

Modify the customField linked to the specified customField id. Only the fields included in the payload will be updated; all others will remain unchanged. Reducing the length of a custom field or changing its associated merge tag is not allowed.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
`customFieldIdToUpdate`	path	string	Yes	The unique identifier for a customField in UUID format

Request body

Optional.

Fields

Field	Type	Required	Description
`label`	string	No	Custom field label
`maxLength`	integer	No	Custom field max length

Example

{
  "label": "Contact field new name",
  "maxLength": 50
}

Responses

200 — CustomField updated

Field	Type	Required	Description
`id`	string	Yes	Custom field id in UUID format
`accountId`	string	Yes	Account id
`vendorId`	string	Yes	Vendor id
`label`	string	Yes	Custom field label
`mergeTag`	string	Yes	Custom field merge tag
`maxLength`	integer	Yes	Custom field max length
`type`	enum: DATE, NUMBER, PHONE, TEXT, URL, ZIP_CODE, NAME, EMAIL	Yes	Custom field type
`createdDate`	string	Yes	Create date
`lastModifiedDate`	string	Yes	Last modified date

Example:

{
  "id": "025e93d3-051b-43f9-b12e-4b5842228dee",
  "accountId": "accountId_67846328",
  "vendorId": "string",
  "label": "Contact field new name",
  "mergeTag": "contact_name",
  "maxLength": 50,
  "type": "DATE",
  "createdDate": "2022-08-18T09:15:03.112Z",
  "lastModifiedDate": "2022-08-18T09:15:03.112Z"
}

400 — Request has incorrect values

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details
`invalidFields`	array of InvalidInputField	Yes	List of invalid fields
`invalidFields[].name`	string	No
`invalidFields[].channelType`	string	No
`invalidFields[].code`	string	No
`invalidFields[].reason`	string	No
`invalidFields[].invalidIds`	array of string	No

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "validation",
  "title": "string",
  "detail": "string",
  "invalidFields": [
    {
      "name": "string",
      "channelType": "PHONE",
      "code": "must_not_be_empty",
      "reason": "string",
      "invalidIds": [
        "string"
      ]
    }
  ]
}

401 — No valid authentication details were provided

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unauthorized",
  "title": "Title",
  "detail": "Extra details"
}

403 — The authenticated user or account doesn't have permission

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "forbidden",
  "title": "Title",
  "detail": "Extra details"
}

409 — Conflict. The CustomField already exists.

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "conflict",
  "title": "Title",
  "detail": "Extra details"
}

500 — Internal server error

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "internal_server_error",
  "title": "Internal error",
  "detail": "Extra details"
}

501 — Request not recognised

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "request_not_recognised",
  "title": "Internal error",
  "detail": "Extra details"
}

502 — Invalid server response

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "bad_gateway",
  "title": "Title",
  "detail": "Extra details"
}

503 — Server currently unavailable

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

504 — Gateway time out

Field	Type	Required	Description
`uuid`	string	Yes	Error id in UUID format
`type`	enum: validation, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, message_not_readable, internal_server_error, request_not_recognised, forbidden, bad_gateway, payment_required, unauthorized, unknown	Yes	Error type
`title`	string	Yes	Error title
`detail`	string	Yes	Error additional details

Example:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "unknown",
  "title": "Internal error",
  "detail": "Extra details"
}

Example request

curl -X PATCH "https://api.etxtservice.co.nz/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"Contact field new name","maxLength":50}'

Overview

Base URI

Authentication

Basic Authentication

Example request with Basic Authentication

HMAC Authentication

To create this header

Step 1

Step 2

Step 3

Step 4

Step 5

Example request with body

Example request without body

Contents

Contacts

Retrieve Contacts

Parameters

Responses

200 — Returns a contacts page

400 — Request has incorrect values

401 — No valid authentication details were provided

403 — The authenticated user or account doesn't have permission

500 — Internal server error

501 — Request not recognised

502 — Invalid server response

503 — Server currently unavailable

504 — Gateway time out

Example request

Create Contact

Request body

Fields

Example

Responses

201 — Contact succesfully created

400 — Request has incorrect values

401 — No valid authentication details were provided

403 — The authenticated user or account doesn't have permission

409 — Conflict. The contact already exists.

500 — Internal server error

501 — Request not recognised

502 — Invalid server response

503 — Server currently unavailable

504 — Gateway time out

Example request

Get Contact

Parameters

Responses

200 — Contact requested data

400 — Request has incorrect values

401 — No valid authentication details were provided

403 — The authenticated user or account doesn't have permission

500 — Internal server error

501 — Request not recognised

502 — Invalid server response

503 — Server currently unavailable

504 — Gateway time out

Example request

Delete Contact

Parameters

Responses

204 — No Content

400 — Request has incorrect values

401 — No valid authentication details were provided

403 — The authenticated user or account doesn't have permission

500 — Internal server error

501 — Request not recognised

502 — Invalid server response

503 — Server currently unavailable

504 — Gateway time out

Example request

Update Contact

Parameters

Request body

Fields

Example

Responses

200 — Contact updated

400 — Request has incorrect values

401 — No valid authentication details were provided