Self Service

Introduction

Welcome to the CRM.COM Application Programming Interface (API) documentation

The CRM.COM API is designed around REST, allowing you to manage subscription and/or rewards commerce in a simple, programmatic way using intuitive URL endpoints, conventional HTTP requests, response codes, authentication and verbs.

Self-Service API is designed with the main focus on developers of Mobile or Web based Applications, while being secure and performant.

For the management API please refer to the Back-Office API documentation that provides access and extensibilty to the functionality found in the CRM.COM.

Authentication

The CRM.COM Self Service API uses a JWT token that is returned from a contact authentication call either using user / password or One Time Password request.

A pubic api key should be provided as part of the header for application identification, i.e. -H “api_key : crm_test_;dwfwgiuhjr412edws”

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Example 1
curl -X POST \
  https://api.crm.com/selfservice/v3/contact/98765432/paymentmethod \
  -H 'Authorization: Bearer secret_U0tfZGtqYXNmZGJob2VJUkZKRVdGSjo=' \
  -H 'api_key: 8c54d563-b991-4b76-8a83-557c08166f95' \
  -H 'Content-Type: application/json' \ 
  -d '{
    "accounts": [{
        "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
        "opt_in_subscriptions": true,
        "opt_in_purchases": true,
        "use_primary": false
    }],
    "payment_method_type": "STRIPE",
    "card": {
        "gateway_tokens": [{
            "gateway": "STRIPE",
            "token": "strp_dwfgrjefegrfew"
        }]
    }
}’
Error Codes

CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request

  • 2xx success status codes confirm that your request worked as expected
  • 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
  • 5xx error status codes are rare and indicate an error with Stripe’s servers

Please note that some 4xx errors that could be handled programmatically (e.g. a contact already exists) contain the following informaiion

  • HTTP Code (programmatic consumption)
  • Message (human-readable)
  • Attribute (attribute that caused the error)

Below is a list of our common error codes that can be returned, along with additional information about how to resolve them

200 OK
Applied to all operations

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Responsive Images

The concept of responsive images is utilized, offering single images that can respond to changes in any screen resolution on any mobile and/or web-based applications.

In order to achieve that applications should use an <img> atttribute named srcset. The srcset defines multiple sizes of the same image, allowing the browser to select the appropriate image source based on its current resolution.

Example 1
<img srcset="small.jpg 256w,
            medium.jpg 512w,
			large.jpg 1024w"
		sizes="(max-width: 30em) 25em, 100vw"
		src="medium.jpg"
		alt="responsive image" />
Operations
Authentication

Ability to authenticate customers via a Mobile App or a Portal

POST /contacts/authenticate
POST /contacts/otp
POST /contacts/refresh
POST /contacts/validate-otp
POST /contacts/forgot_password
POST /contacts/change_password
POST /contacts/{id}/change_password
POST /contacts/{id}/sign_out
POST /contacts/verify_email
Authenticate Contact
POST /contacts/authenticate

Authenticate a contact and provide a token for subsequent API access

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060

Request body

Object
provider
string required

The contact’s identity provider

Enumeration:
EMAIL
FACEBOOK
GOOGLE
PHONE

PENDING

MW4

CRM.COM auth server

username
string required nullable

The contact’s username (required for EMAIL)

Example:
johndoe@crm.com
password
string required nullable

The contact’s password (required for EMAIL)

Example:
password1234
token
string required nullable

The token taken from the oAUTH service provider (required for Facebook and Google providers)

Example:
234er43ergt34eett34
phone_number
string required nullable

The contact’s phone number (required for PHONE)

Example:
21000000
country_code
string required nullable

The contact’s phone number country code (required for PHONE)

Example:
CYP
Examples

Responses

200 OK

The request has succeeded

Body
Object
access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
exp
string epoch

The token expiration date

Example:
1572530655
contact
Object

Details about the authorised contact

title
string

The contact’s title

Example:
Mr
first_name
string

The contact’s first name

Example:
John
last_name
string

The contact’s last name

Example:
Doe
avatar
string

The contact’s avatar

Example:
avatar
is_verified
boolean

Defines whether the used identity is verified

Example:
false
organisations
Array

Details about the organisations that the contact has joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
SERVICE_OWNER
ORGANISATION
org_relationship
string

The organisation relationship

Enumeration:
BUSINESS
SUBSIDIARY
MERCHANT
name
string

The organisation name

Example:
CRMdotCOM
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
Example 3
POST /contacts/authenticate HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "provider": "EMAIL",
    "username": "johndoe@crm.com",
    "password": "password1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
    "exp": "1572530655",
    "contact": {
        "title": "Mr",
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "avatar",
        "is_verified": "false"
    },
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "SERVICE_OWNER",
            "org_relationship": "MERCHANT",
            "name": "CRMdotCOM"
        }
    ]
}
POST /contacts/authenticate HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "provider": "GOOGLE",
    "token": "GOOGLEID1234567"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
    "exp": "1572530655",
    "contact": {
        "title": "Mr",
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "avatar",
        "is_verified": "false"
    },
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "ORGANISATION",
            "org_relationship": "MERCHANT",
            "name": "CRMdotCOM"
        }
    ]
}
POST https://sandbox.crm.com/self-service/v1/contacts/authenticate HTTP/1.1 

api_key: ab5f8b2e-092f-4848-8f46-31df1c014060
Content-Type: application/json

{
    "provider": "MW4",
    "token": "234er43ergt34eett34"
}
Request One Time Password
POST /contacts/otp

Request a one time password for a specific contact. The request will identify the contact details and send an outbound validation number that can be used to verify the contact

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060

Request body

Object
send_method
string required

How to send the validation code

Enumeration:
EMAIL
SMS
credentials
Array required

Information on how the contact will be identified

Object
name
string

The predetermined information that will be used to identify the contact

Enumeration:
BIRTHDATE

Lookup on contact details

PASSPORT

Lookup on contact details

ID_NUMBER

Lookup on contact details

CARD

Lookup on contact customer identification medium (if enabled) and then on contact details

PHONE

Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details

EMAIL

Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details

value
string

The value of the credential to check

Example:
1234567

Responses

200 OK

The request has succeeded

Body
Object
obfuscated_value
string

The obfuscated send method value

Example:
+35799***834
auth_otp
string

The one time password auth id

Example:
731e4023-4c04-4278-8eb5-240651317e46
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/otp HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "send_method": "SMS",
    "credentials": [
        {
            "name": "ID_NUMBER",
            "value": "1234567"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "obfuscated_value": "+35799***834",
    "auth_otp": "731e4023-4c04-4278-8eb5-240651317e46"
}
Refresh Token
POST /contacts/refresh

Authenticate a contact and provide a token for subsequent API access

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060
refresh_token
string required

Refresh Token supplied when authenticated

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg

Responses

200 OK

The request has succeeded

Body
Object
access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
exp
string epoch

The token expiration date

Example:
1572530655
contact
Object

Details about the authorised contact

title
string

The contact’s title

Example:
Mr
first_name
string

The contact’s first name

Example:
John
last_name
string

The contact’s last name

Example:
Doe
avatar
string

The contact’s avatar

Example:
avatar
is_verified
boolean

Defines whether the used identity is verified

Example:
false
organisations
Array

Details about the organisations that the contact has joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
SERVICE_OWNER
ORGANISATION
org_relationship
string

The organisation relationship

Enumeration:
BUSINESS
SUBSIDIARY
MERCHANT
name
string

The organisation name

Example:
CRMdotCOM
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/self-service/v1/contacts/refresh HTTP/1.1 

api_key: ab5f8b2e-092f-4848-8f46-31df1c014060
Content-Type: application/json

{
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
    "exp": "1572530655",
    "contact": {
        "title": "Mr",
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "avatar",
        "is_verified": "false"
    },
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "ORGANISATION",
            "org_relationship": "SUBSIDIARY",
            "name": "CRMdotCOM"
        }
    ]
}
Validate One Time Password
POST /contacts/validate-otp

Verifies an one time password that was requested

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060

Request body

Object
credentials
Array required

Information on how the contact will be identified

Object
name
string required

Contact identification credentials

Enumeration:
AUTH_OTP

One Time Password Auth Id

EMAIL

The email address that was used to request the otp

PHONE

The phone number that was used to request the otp

ID_NUMBER

The contact’s id number that was used to request the otp

PASSPORT

The contact’s passport that was used to request the otp

BIRTHDATE

The contact’s birthdate that was used to request the otp

CARD

The contact’s card that was used to request the otp

value
string required

The value of the credential to verify the contact’s authenticity

Example:
12345
code
string required

The OTP that should be used for verification purposes

Example:
123456789
Examples

Responses

200 OK

The request has succeeded

Body
Object
access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
exp
string epoch

The token expiration date

Example:
1572530655
contact
Object

Details about the authorised contact

title
string

The contact’s title

Example:
Mr
first_name
string

The contact’s first name

Example:
John
last_name
string

The contact’s last name

Example:
Doe
avatar
string

The contact’s avatar

Example:
avatar
is_verified
boolean

Defines whether the used identity is verified

Example:
false
organisations
Array

Details about the organisations that the contact has joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
SERVICE_OWNER
ORGANISATION
org_relationship
string

The organisation relationship

Enumeration:
BUSINESS
SUBSIDIARY
MERCHANT
name
string

The organisation name

Example:
CRMdotCOM
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/validate-otp HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "credentials": [
        {
            "name": "AUTH_OTP",
            "value": "12345"
        }
    ],
    "code": "123456789"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
    "exp": "1572530655",
    "contact": {
        "title": "Mr",
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "avatar",
        "is_verified": "false"
    },
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "SERVICE_OWNER",
            "org_relationship": "SUBSIDIARY",
            "name": "CRMdotCOM"
        }
    ]
}
Forgot Password
POST /contacts/forgot_password

Requests a password reset for an existing contact

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060

Request body

Object
username
string required

The username that will be used to request a new password

Example:
johndoe@crm.com
Examples

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/forgot_password HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "username": "johndoe@crm.com"
}

HTTP/1.1 200 OK 
Change Forgotten Password
POST /contacts/change_password

Changes the password for a contact’s identity (EMAIL based)

Request body

Object
token
string required

The token that will verify that the client is trusted (required only if the identity is EMAIL based)

Example:
ABCTKN123456798VGP2020
password
string required

The new password

Example:
wsxcde421qadfg
Examples

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/change_password HTTP/1.1 

Content-Type: application/json

{
    "token": "ABCTKN123456798VGP2020",
    "password": "wsxcde421qadfg"
}

HTTP/1.1 200 OK 
Change Password
POST /contacts/{id}/change_password

Changes the password for a contact’s identity (EMAIL based)

Path variables

id
string GUID required

The contact identifier whose password will be changed

Example:
0980af1d-3c24-6379-9eb9-a40e3a3f5208

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
password
string required

The new password

Example:
wsxcde421qadfg
Examples

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/0980af1d-3c24-6379-9eb9-a40e3a3f5208/change_password HTTP/1.1 

Content-Type: application/json
Authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "password": "wsxcde421qadfg"
}

HTTP/1.1 200 OK 
Sign Out Contact
POST /contacts/{id}/sign_out

Terminates the contact’ session and will no longer be able to access the client

Path variables

id
string GUID required

The contact identifier that will be signed out

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/sign_out HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Verify Contact Email
POST /contacts/verify_email

Verify a contact’s email address username

Request parameters

token
string required

The token that will used for verifying the contact’s email address

Example:
ABCTKN123456798VGP2020

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/verify_email?token=ABCTKN123456798VGP2020 HTTP/1.1 

HTTP/1.1 200 OK 
Communications
GET /contacts/{id}/communications
GET /communications/{id}
PUT /communications/{id}/actions
List Communications
GET /contacts/{id}/communications

Get a list of a contact’s communications

Path variables

id
string GUID required

The contact identifier for which the related communications will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Allow empty value: true
Examples:
CREATED_DATEUPDATED_DATENAME
order
string optional

Defines how the results will be ordered

Allow empty value: true
Enumeration:
ASC
DESC
Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
Example:
20
size
string optional

The size (total records) of each page

Default:
10
Example:
20
channel
string optional

The type of the communications to be retrieved

Enumeration:
EMAIL
SMS
DEVICE
INAPP
archived
boolean optional

If set to TRUE, only archived communications will be retrieved

Example:
true
viewed
boolean optional

If set to TRUE, only viewed communications will be retrieved

Example:
true

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 200

The request has succeeded

Body
application/json
Object
content
Array

Information about the retrieved communication records

Object
id
string GUID

The communication identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
life_cycle_state
string

The state of the communication

Enumeration:
PENDING
COMPLETED
REJECTED
Example:
PENDING
contact_id
string GUID

The contact identifier that communication was sent to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
Example:
EMAIL
is_viewed
boolean

Defines whether the communication has been viewed

Example:
false
viewed_on
integer epoch

The datetime that the recipient viewed the communication

Example:
1583846865
is_archived
boolean

Defines whether the communication has been archived

Example:
true
clicked_on
integer epoch

The date links in the communication where first clicked by the recipient

language
string

The language tha the communication was sent in

Example:
ENG
sender
string

The default sender

Example:
dev@crm.com
recipient
string

The email or number of the recipient

Example:
jon@crm.com
content
string

The actual content of the communication sent

subject
string

The actual subject of the communication sent (if applicable)

name
string

The name of the communication plan in case the communication was created from a plan

Example:
Happy Birthday
paging
Object

Information that can be used in order to display large pages

page
integer

The page number

Example:
2
size
integer

The number of records per page

Default:
10
Example:
20
total
integer

The total number of records

Example:
1124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/self-service/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/communications HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "life_cycle_state": "PENDING",
            "contact_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "channel": "EMAIL",
            "is_viewed": true,
            "viewed_on": 1583846865,
            "is_archived": true,
            "clicked_on": 1,
            "language": "ENG",
            "sender": "dev@crm.com",
            "recipient": "jon@crm.com",
            "content": "",
            "subject": "",
            "name": "Happy Birthday"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 1124
    }
}
Get Communications
GET /communications/{id}

Get a specific contact’s communication

Path variables

id
string GUID required

The communication identifier that should be returned

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 200

The request has succeeded

Body
application/json
Object
life_cycle_state
string

The state of the communication

Enumeration:
PENDING
COMPLETED
REJECTED
Example:
PENDING
contact
Object
id
string GUID

The unique identifier of the contact

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The full name of the contact

Example:
John Johnson
code
string

The unique code of the contact

Example:
C123
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
Example:
EMAIL
is_viewed
boolean

Defines whether the communication has been viewed

Example:
false
viewed_on
integer epoch

The datetime that the recipient viewed the communication

Example:
1583846865
is_archived
boolean

Defines whether the communication has been archived

Example:
true
clicked_on
integer epoch

The date links in the communication where first clicked by the recipient

language
string

The language tha the communication was sent in

Example:
ENG
sender
string

The default sender

Example:
dev@crm.com
recipient
string

The communication’s recipient information

Example:
jon@crm.com
subject
string

The actual subject of the communication sent (if applicable)

Example:
Award Provided
content
string

The actual content of the communication sent

Example:
You have been awarded!
name
string

The name of the communication plan in case that the communication was created based on a plan

Example:
Happy Birthday
created_on
integer epoch

The date and time that the communication was created

Example:
1583846865
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/self-service/v1/communications/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "life_cycle_state": "PENDING",
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "channel": "EMAIL",
    "is_viewed": true,
    "viewed_on": 1583846865,
    "is_archived": true,
    "clicked_on": 1,
    "language": "ENG",
    "sender": "dev@crm.com",
    "recipient": "jon@crm.com",
    "subject": "Award Provided",
    "content": "You have been awarded!",
    "name": "Happy Birthday",
    "created_on": 1583846865
}
Communications Actions
PUT /communications/{id}/actions

Mark an existing communication as viewed and/or archived

Path variables

id
string GUID required

The communication identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
viewed
boolean

Sets the communication as viewed

Example:
true
archived
boolean

Sets the communication as archived

Example:
true

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/self-service/v1/communications/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "viewed": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Contact

Contact Management

POST /contacts/register
PUT /contacts/{id}
PUT /contacts/{id}/consents
GET /contacts/{id}
GET /contacts/{id}/demographics
Register Contact
POST /contacts/register

Create a new contact (of type person)

Request headers

api_key
string required

The publishable api key for application identification

Example:
ab5f8b2e-092f-4848-8f46-31df1c014060

Request body

Object
first_name
string required nullable

The contact first name (required for EMAIL and PHONE providers)

Example:
John
last_name
string required nullable

The contact last name (required for EMAIL and PHONE providers)

Example:
Doe
identity
Object required

Details about the customer’s identity

provider
string required

The identity provider

Enumeration:
EMAIL
PHONE
GOOGLE
FACEBOOK
username
string required nullable

The contact’s username (required for EMAIL)

Example:
johndoe@crm.com
password
string required nullable

The contact’s password (required for EMAIL)

Example:
12345
validation_required
boolean required nullable

Defines whether the username (email) should be verified (required for EMAIL)

Example:
true
phone_number
string required nullable

The contact’s phone number (required for PHONE)

Example:
2265577
country_code
string required nullable

The contact’s phone number country code (required for PHONE)

Example:
CYP
token
string required nullable

The token taken from the oAUTH service provider (required for Facebook and Google)

Example:
YOJDAKEb9l1U0sUzrskM6X4emzrSeXqb
service_acceptance
boolean nullable

Defines whether the contact has accepted the client service

Default:
true
Example:
true
email_opt_out
boolean nullable

The contact setting for receiving emails

Default:
false
Example:
true
sms_opt_out
boolean nullable

The contact setting for receiving sms

Default:
false
Example:
true
consent_state
string

The contact setting for consent

Enumeration:
PENDING
ACCEPTED
REJECTED
WITHDRAWN
referral_code
string nullable
Examples

Responses

200 OK

The request has succeeded

Body
Object
access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
exp
string epoch

The token expiration date

Example:
1572530655
contact
Object

Details about the authorised contact

title
string

The contact’s title

Example:
Mr
first_name
string

The contact’s first name

Example:
John
last_name
string

The contact’s last name

Example:
Doe
avatar
string

The contact’s avatar

Example:
avatar
is_verified
string

Defines whether the used identity is verified

Example:
false
organisations
Array

Details about the organisations that the contact has joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Example:
ORGANISATION
org_relationship
string

The organisation relationship

Example:
MERCHANT
name
string

The organisation name

Example:
CRMdotCOM
obfuscated_value
string

The obfuscated send method value (applicable only when provider is PHONE and an OTP is generated)

Example:
+35799***834
auth_otp
string

The one time password auth id (applicable only when provider is PHONE and an OTP is generated)

Example:
731e4023-4c04-4278-8eb5-240651317e46
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
POST /contacts/register HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "first_name": "John",
    "last_name": "Doe",
    "identity": {
        "provider": "EMAIL",
        "username": "johndoe@crm.com",
        "password": "12345",
        "validation_required": false
    },
    "service_acceptance": "true",
    "email_opt_out": "true",
    "sms_opt_out": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
    "exp": "1572530655",
    "contact": {
        "title": "Mr",
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "avatar",
        "is_verified": "false"
    }
}
POST /contacts/register HTTP/1.1 

api_key: ab5f8b2e-092f-4848-8f46-31df1c014060
Content-Type: application/json

{
    "first_name": "John",
    "last_name": "Doe",
    "identity": {
        "provider": "PHONE",
        "phone_number": "22265577",
        "country_code": "CYP"
    },
    "service_acceptance": "true",
    "email_opt_out": "true",
    "sms_opt_out": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "obfuscated_value": "+35799***834",
    "auth_otp": "731e4023-4c04-4278-8eb5-240651317e46"
}
Update Contact
PUT /contacts/{id}

Updates an existing contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
company_name
string nullable

Company Name if the Contact represents a company, required attribute if the type is a Company.

Example:
Alpha Bravo
title
string nullable

The title of the contact. Applicable only if the type is PERSON

Example:
Sir
first_name
string nullable

The first name of the contact. Applicable and mandatory only if the type is PERSON

Example:
John
middle_name
string nullable

The middle name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Alias
last_name
string nullable

The last name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Doe
preferred_language_code
string nullable

The contact preferred language

Example:
ENG
category_id
string GUID

The contact’s category ID

Example:
4AD9C84FA60F9FE407140E20F707726A
statutory_number
string nullable

The contact statutory number

Example:
EF-12345
demographics
Object nullable

Information about the person demographics

gender
string nullable

The person gender

Enumeration:
MALE
FEMALE
passport
Object nullable

Information about the person passport

passport_number
string

The passport number

Example:
123456
issue_country_code
string

The country that issued the passport

Example:
CYP
expiration_date
integer epoch

The passport expiration date

Example:
129876567
id_details
Object nullable

Information about the person id

id_number
string

The id number

Example:
K123456
issue_country_code
string

The country that issued the id

Example:
CYP
expiration_date
integer epoch

The id expiration date

Example:
129876567
name_day
Object nullable

Information about the person nameday

month
integer required

The nameday month

Example:
10
day
integer required

The nameday day

Example:
4
date_of_birth
Object nullable

Information about the person birthdate

year
integer required

The birth year

Example:
2018
month
integer required

The birth month

Example:
10
day
string required

The birth day

Example:
16
company_profle
Object nullable

A company’s profile. Applicable only if contact_type is COMPANY

profile_year
integer epoch

The company’s profile year

Example:
129876567
annual_turnover
number

The annual turnover

Example:
1568.14
established_on
integer epoch

The date that the company was established on

Example:
129876567
number_of_employees
integer

The company’s number of employees

Example:
1
registration_number
string

The company registration number

Example:
123456
registration_country
string

The country that the company is registered to

Example:
CYP
tax_reference_number
string

The company tax reference number

Example:
123456
vat_registration_number
string

The company vat registration number

Example:
123456
industry_id
string GUID

The company’s Industry ID

Example:
4AD9C84FA60F9FE407140E20F707726A
industry_sectors
Array

The company’s Industry Sectors.

string GUID
Example:
4AD9C84FA60F9FE407140E20F707726A
email_address
string

The contact’s email address

Example:
bill@gmail.com
sms_opt_out
boolean

The contact setting for receiving sms

Example:
false
email_opt_out
boolean

The contact setting for receiving email

Example:
false
is_tax_exempt
boolean

Defiens whether the contact is tax exempt or not

Example:
false

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
658AB90A6A77437091D158FD8E697B11
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Update contact

PUT https://sandbox.crm.com/self-service/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "company_name": "Alpha Bravo",
    "title": "Sir",
    "first_name": "John",
    "middle_name": "Alias",
    "last_name": "Doe",
    "preferred_language_code": "ENG",
    "category_id": "4AD9C84FA60F9FE407140E20F707726A",
    "statutory_number": "EF-12345",
    "demographics": {
        "gender": "MALE",
        "passport": {
            "passport_number": "123456",
            "issue_country_code": "CYP",
            "expiration_date": 129876567
        },
        "id_details": {
            "id_number": "K123456",
            "issue_country_code": "CYP",
            "expiration_date": 129876567
        },
        "name_day": {
            "month": 10,
            "day": 4
        },
        "date_of_birth": {
            "year": 2018,
            "month": 10,
            "day": "16"
        }
    },
    "company_profle": {
        "profile_year": 129876567,
        "annual_turnover": 1568.14,
        "established_on": 129876567,
        "number_of_employees": 1,
        "registration_number": "123456",
        "registration_country": "CYP",
        "tax_reference_number": "123456",
        "vat_registration_number": "123456",
        "industry_id": "4AD9C84FA60F9FE407140E20F707726A",
        "industry_sectors": [
            "4AD9C84FA60F9FE407140E20F707726A"
        ]
    },
    "email_address": "bill@gmail.com",
    "sms_opt_out": "false",
    "email_opt_out": "false",
    "is_tax_exempt": "false",
    "consent_state": "ACCEPTED"
}
PUT /contacts/{id}/consents

Updates the Consent state of the Contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
consent_state
string

The consent state to be updated

Enumeration:
PENDING
ACCEPTED
REJECTED
WITHDRAWN

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
658AB90A6A77437091D158FD8E697B11
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Update contact

PUT https://sandbox.crm.com/self-service/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/consents HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "consent_state": "ACCEPTED"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "658AB90A6A77437091D158FD8E697B11"
}
Get Contact
GET /contacts/{id}

Retrieve basic details for a specific contact

Path variables

id
string GUID required

The contact identifier that should be returned

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The contact code

Example:
ABC-123
type
string

Tje contact type

Enumeration:
PERSON
COMPANY
title
string

The contact title

Example:
Sir
first_name
string

The contact first name

Example:
John
middle_name
string

The contact middle name

Example:
Alias
last_name
string

The contact last name

Example:
Doe
preferred_language_code
string

The contact preferred language

Example:
ENG
avatar_url
string

The contact URL of Avatar

email
string

The contact email address

Example:
jon@crm.com
referral_code
string

The contact referral code

Example:
REF123
loyalty_identifier
Array

The contact loyalty identifiers

Object
identifier
string

The contact loyalty identifier

Example:
123423435434534534543
sms_opt_out
boolean

The contact setting for receiving sms

Example:
false
email_opt_out
boolean

The contact setting for receiving email

Example:
true
consent_state
string

The contact consent

Enumeration:
PENDING
ACCEPTED
REJECTED
WITHDRAWN
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "ABC-123",
    "type": "COMPANY",
    "title": "Sir",
    "first_name": "John",
    "middle_name": "Alias",
    "last_name": "Doe",
    "preferred_language_code": "ENG",
    "avatar_url": ""
}
Get Contact Demographics
GET /contacts/{id}/demographics

Retrieves the demographics of a signle contact

Path variables

id
string required

The unique ID for which the demographics will be returned

Responses

200 OK
Body
Object
gender
string
Example:
FEMALE
passport
Object
number
string
Example:
K123456
issue_country_code
string
Example:
CYP
expiration_date
integer
Example:
129876567
id_details
Object
number
string
Example:
123456
issue_country_code
string
Example:
CYP
expiration_date
integer
Example:
129876567
name_day
Object
month
integer
Example:
10
day
integer
Example:
4
date_of_birth
Object
year
integer
Example:
1990
month
integer
Example:
10
day
integer
Example:
16
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /contacts/{id}/demographics HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "gender": "FEMALE",
    "passport": {
        "number": "K123456",
        "issue_country_code": "CYP",
        "expiration_date": 129876567
    },
    "id_details": {
        "number": "123456",
        "issue_country_code": "CYP",
        "expiration_date": 129876567
    },
    "name_day": {
        "month": 10,
        "day": 4
    },
    "date_of_birth": {
        "year": 1990,
        "month": 10,
        "day": 16
    }
}
Addresses
POST /contacts/{id}/addresses
PUT /contacts/{id}/addresses/{address_id}
DELETE /contacts/{id}/addresses/{address_id}
GET /contacts/{id}/addresses
Add Contact Address
POST /contacts/{id}/addresses

Add a new address to an existing contact. A contact can have multiple addresses

Path variables

id
string GUID required

The contact identifier for which an address will be added

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
address_type
string required

The address type

Enumeration:
HOME
BUSINESS
address_line_1
string required

The address line 1

Example:
Elia Papakyriakou
address_line_2
string nullable

The address line 2

Example:
Tower Star
state_province_county
string nullable

The address county

Example:
Egkomi
town_city
string nullable

The address city

Example:
Nicosia
postal_code
string nullable

The address postal code

Example:
2000
country_code
string required

The address country identifier

Example:
CY
is_primary
boolean nullable

Defines whether the address is the primary one

Example:
true
lat
number nullable

The address geolocation latitude

Example:
12.212
lon
number nullable

The address geolocation longtitude

Example:
12.234
googlePlaceId
string nullable

The Google textual identifier that uniquely identifies an address

Example:
234242423424
care_of
string nullable

The address care of

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The address record identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "address_type": "BUSINESS",
    "address_line_1": "Elia Papakyriakou",
    "address_line_2": "Tower Star",
    "state_province_county": "Egkomi",
    "town_city": "Nicosia",
    "postal_code": "2000",
    "country_code": "CY",
    "is_primary": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Contact Address
PUT /contacts/{id}/addresses/{address_id}

Update an existing address of a contact

Path variables

id
string GUID required

The contact identifier for which an address should be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_id
string GUID required

The address identifier that should be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
address_line_1
string nullable

The address line 1

Example:
Elia Papakyriakou
address_line_2
string nullable

The address line 2

Example:
Tower Star
state_province_county
string nullable

The address county

Example:
Egkomi
town_city
string nullable

The address city

Example:
Nicosia
postal_code
string nullable

The address postal code

Example:
2000
country_code
string nullable

The address country identifier

Example:
CY
care_of
string nullable

The address care of

is_primary
boolean nullable

Defines whether the address is the primary one

Example:
true
lat
number nullable

The latitude of the address

Example:
12.456
lon
number nullable

The longitude of the addrsss

Example:
11.231
googlePlaceId
string nullable

The Google textual identifier that uniquely identifies an address

Example:
12312424324

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The address record identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "address_line_1": "Elia Papakyriakou",
    "address_line_2": "Tower Star",
    "state_province_county": "Egkomi",
    "town_city": "Nicosia",
    "postal_code": "2000",
    "country_code": "CY",
    "care_of": "",
    "is_primary": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Remove Contact Address
DELETE /contacts/{id}/addresses/{address_id}

Remove an existing address from a specific contact

Path variables

id
string GUID required

The contact (id) from which the address will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_id
string GUID required

The address identifier that should be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Remove an existing contact address

DELETE /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Contact Addresses
GET /contacts/{id}/addresses

Retrieve the addresses of a specific contact

Path variables

id
string GUID required

The contact identifier for which his/her addresses will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The address identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
address_type
string

The address’ type

Enumeration:
HOME
BUSINESS
address_line_1
string

The address line 1

Example:
Elia Papakyriakou 1
address_line_2
string

The address line 2

Example:
Tower Star
state_province_county
string

The address county

Example:
Egkomi
town_city
string

The address city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2000
country_code
string

The address country identifier

Example:
CY
is_primary
boolean

Defines whether the address is the primary one

Example:
true
lat
number

The address geolocation latitude

Example:
12.234
lon
number

The address geolocation longtitude

Example:
12.234
googlePlaceId
string

The unique Google identifier for the address

Example:
32342432342wer23
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "type": "HOME",
            "address_line_1": "Elia Papakyriakou 1",
            "address_line_2": "Tower Star",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2000",
            "country_code": "CY",
            "is_primary": "true"
        }
    ]
}
Devices
POST /contacts/{id}/devices
GET /contacts/{id}/devices
Add Contact Devices
POST /contacts/{id}/devices

Add devices to a contact

Path variables

id
string GUID required

The contact (id) for which a device will be added

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
serial_number
string

The device’s serial number or device ID

Example:
00000000-000000000000000
registration_type
string

The device’s registration type

Enumeration:
IOS
ANDROID
registration_token
string

The device’s registration token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/devices HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "serial_number": "00000000-000000000000000",
    "registration_type": "ANDROID",
    "registration_token": "4AD9C84FA60F9FE407140E20F707726A"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Contact Devices
GET /contacts/{id}/devices

Get a list of contact devices.

Path variables

id
string GUID required

The contact identifier for which a list of devices will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Allow empty value: true
Examples:
CREATED_DATEUPDATED_DATENAME
order
string optional

Defines how the results will be ordered

Allow empty value: true
Enumeration:
ASC
DESC
Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
Example:
20
size
string optional

The size (total records) of each page

Default:
10
Example:
20

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
device_id
string GUID

The device identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
serial_number
string

The device’s serial number which can also be the device id

Example:
00000000-000000000000000
registration_token
string

The device’s registration token

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
registration_type
string

The device’s registration type based on the device’s product and the communication settings, which can be either Android or IOS

Enumeration:
IOS
ANDROID
paging
Object

Information that can be used in order to display large pages

page
integer

The page number

Example:
2
size
integer

The number of records per page

Default:
10
Example:
20
total
integer

The total number of records

Example:
1124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/devices HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "device_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "serial_number": "00000000-000000000000000",
            "registration_token": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "registration_type": "IOS"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 1124
    }
}
Files
POST /contacts/{id}/files
GET /contacts/{id}/files
Add Contact Files
POST /contacts/{id}/files

Add a new file to a Contact

Path variables

id
string GUID required

The contact identifier for which a file will be added

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
id
string GUID

The unique identifier of the file to be added

Example:
4AD9C84FA60F9FE407140E20F707726A
description
string

A description of the file added

Example:
This is the proof of address
Examples

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/files HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A",
    "description": "This is the proof of address"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Contact Files
GET /contacts/{id}/files

Retrieve an existing Contact’s files

Path variables

id
string GUID required

The contact identifier for which the files will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Allow empty value: true
Examples:
CREATED_DATEUPDATED_DATENAME
order
string optional

Defines how the results will be ordered

Allow empty value: true
Enumeration:
ASC
DESC
Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
Example:
20
size
string optional

The size (total records) of each page

Default:
10
Example:
20

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The id of the file

Example:
4AD9C84FA60F9FE407140E20F707726A
description
string

The description of the file

Example:
This is the proof of address
paging
Object

Information that can be used in order to display large pages

page
integer

The page number

Example:
2
size
integer

The number of records per page

Default:
10
Example:
20
total
integer

The total number of records

Example:
1124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/files HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "description": "This is the proof of address"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 1124
    }
}
Payment Methods
POST /contacts/{id}/payment_methods
PUT /contacts/{id}/payment_methods/{payment_method_id}
DELETE /contacts/{id}/payment_methods/{payment_method_id}
GET /contacts/{id}/payment_methods
POST /contacts/{id}/intents
Add Payment Methods
POST /contacts/{id}/payment_methods

Add a new payment method for a contact supports BANK, CREDIT / DEBIT cards, or Payment Gateways such as Paypal.

Path variables

id
string GUID required

The contact identifier for which a payment method will be added

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

Authorization
string required

Authorization Token

Example:
4AD9C84FA60F9FE407140E20F707726A

Request body

Object
id
string

Unique identifier for the payment method, if not specified it will be auto generated

Example:
34234234-34343
payment_method_type
string required

The payment method that will be related with the account

Enumeration:
CARD
DIRECT_DEBIT
PAYPAL
WALLET
ACCOUNT
is_primary
boolean

Marks the payment method as the contact’s primary one

Example:
true
is_backup
boolean

Marks the payment method as the backup

Example:
false
notes
string nullable

Notes related to te payment method

Example:
Lorem Ipsum
bank_details
Object required nullable

The bank details.Required and applicable if the payment method is set to BANK

account_holder_name
string nullable

The account holder name of the bank

Example:
John Doe
account_number
string required nullable

The bank account number. Either the bank account number or IBAN must be specified

Example:
001002001
sort_code
string nullable

The bank sort code

Example:
102491
iban
string required nullable

The IBAN code. Either the bank account number or IBAN must be specified

Example:
SE3550000000054910000003
bank
string nullable

The identifier of the bank

Example:
Barclays
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string

The bank account swift number

Example:
12345678