Self Service
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.
CRM.COM API is organized around REST. Our API has specific resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication & verbs.
You can use the entire API in test mode, which does not affect your live data. The API Key used to authenticate any of your requests will determine whether the request is on live mode or test mode.
The API may differ based on each CRM.COM release. For every new release with noticable changes that might alter backwards compatibility, a new version will be created.
The CRM.COM Self Service API uses a JWT token that is returned from a contact authentication call either using username & password or one time password request.
All API requests must be made over HTTPS. Any request made over plain HTTP or without authentication will fail. A pubic api key should be provided as part of the header for application identification.
API KEY AUTHORIZATION HEADER EXAMPLE
curl -X $HTTP_METHOD -H "api_key: 2189341e-981e-9ad5-9912-11101670314a"
AUTH TOKEN AUTHORIZATION HEADER EXAMPLE
curl -X $HTTP_METHOD -H "authorization: Bearer JWT_TOKEN"
API requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.
| Method | Usage |
|---|---|
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object to the targeted endpoint. |
| PUT | To update the information on an existing object, the PUT method should be used. This will update the specified object if it is found using the provided values, regardless of their current values. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource’s availability prior to issuing an update command, the final state will be the same regardless of its existence. Requests using the PUT method do not need to check the current attributes of the object. |
| DELETE | To remove an existing object from your environment, the DELETE method should be used. Similar to PUT method, the DELETE method is idempotent. |
| GET | For retrieving information about customers, purchases or orders, the GET method should be used. Any requested information will be returned as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the retrieved objects. |
Along with the HTTP methods that the API responds to, CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request.
In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.
| HTTP Status | Description |
|---|---|
| 2XX | Return codes in the 200 range indicate that the request was fulfilled successfully and that no error was encountered. |
| 4XX | Return codes in the 400 range, typically, indicate that there was an issue with the request that was sent. Most common reasons could be an invalid authentication method, unauthorised requests or the object that you are requesting does not exist. |
| 5XX | Return codes in the 500 range indicate that there is a server-side problem and CRM.COM cannot fulfill your request at the moment. |
Most of our 4XX range errors that could be handled programmatically contain all the necessary details for a better integration handling. Such details are
- HTTP Status Code & Error are used for programmatic consumption
- Message is human-readable and can be used as a default error message
- Parameters are used for programmatic consumption and can be used for enhancing the interface error message with additional information
4XX ERROR RESPONSE EXAMPLE
An example of a customer not found error is as follows
HTTP/1.1 400 Bad Request
{
"status": 400,
"message": "Record not found.",
"error": "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION",
"parameters": [
"contact",
"789dacae-cf71-414f-9483-ca88acaa46432"
]
}
The request has succeeded
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server did not receive a timely response from the upstream server
The concept of responsive images is utilized, offering single images that can respond to changes in any screen resolution on any mobile 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.
<img
srcset="small.jpg 256w,
medium.jpg 512w,
large.jpg 1024w"
sizes="(max-width: 30em) 25em, 100vw"
src="medium.jpg"
alt="responsive image"
/>{id}/approval_requests{id}/actions{id}/approval_requestsRetrieve all approval requests for a specific contact
Path variables
The contact (identifier) for which the related approval requests will be retrieved
Request parameters
Filter based on approval request state
Filter based on the entity type that such requests are applied to
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
Authorization Token
Responses
Body
The approval request identifier
The approval request state
Details about the entity that such approval request was applied to
The entity identifier
The approval entity type
The entity reference name/code/number
Information that can be used in order to display large pages
The page number
The number of records per page
The total number of records
GET https://sandbox.crm.com/self-service/v1/contacts/b2157d75-7959-83dc-fdfa-cacba764d4d4/approval_requests HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "8dfc2223-edca-f05d-820b-dc96ba9df2c2",
"state": "APPROVED",
"entity": {
"id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
"type": "ORDER",
"reference": "CO1234"
}
}
],
"paging": {
"page": 2,
"size": 20,
"total": 1124
}
}{id}/actionsUpdate an existing approval request
Path variables
The approval request (identifier) that will be updated
Request headers
Authorization Token
Request body
Defines the action that will be applied on the approval request
Responses
Body
The approval request identifier
POST https://sandbox.crm.com/self-service/v1/approval_requests/a6ecbc14-5622-0e30-b629-b1289963f7d2/actions HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json
{
"action": "REJECT"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a6ecbc14-5622-0e30-b629-b1289963f7d2"
}Accept a pending approval request
Request body
The token that will verify that the client is trusted and will approve the related request
Responses
Body
An HTML based landing page is returned and rendered
POST https://sandbox.crm.com/self-service/v1/approval_requests/64a29ac3-48bb-7493-1e9d-45c1c3299a51/actions HTTP/1.1
Content-Type: application/json
{
"token": "367a4c39-d69a-a0e7-7b6f-4eccf65449a3",
"response": "REJECT"
}
HTTP/1.1 200 OK Reject a pending approval request
Request body
The token that will verify that the client is trusted and will approve the related request
Responses
Body
An HTML based landing page is returned and rendered
POST https://sandbox.crm.com/self-service/v1/approval_requests/64a29ac3-48bb-7493-1e9d-45c1c3299a51/actions HTTP/1.1
Content-Type: application/json
{
"token": "367a4c39-d69a-a0e7-7b6f-4eccf65449a3",
"response": "REJECT"
}
HTTP/1.1 200 OK Create an upload signature for a file
Notes
Integrating file upload should be based on the following APIs
- Upload file signature
- Connect file to a module (entity), such as service requests
Request headers
Authorization Token
Request body
File contents provided via multipart/form-data
Examples
Responses
The response succeeded
Body
The file identifier that will be used for connecting the file with a module
POST https://sandbox.crm.com/self-service/v1/upload/files HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json
{
"file": "file object"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "7279fecf-b0a6-0aab-6bcd-37881fe8c10e"
}{id}Delete a file
Path variables
The file identifier to be deleted
Request headers
Authorization Token
Responses
DELETE https://sandbox.crm.com/self-service/v1/service_requests/6b888b83-b418-752f-604d-0653cf65885d/files/8dfc2223-edca-f05d-820b-dc96ba9df2c2 HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK {id}Retrieve a specific file
Path variables
The file (identifier) to be retrieved
Request headers
Authorization Token
Responses
The request has succeeded
Body
The identifier of the file retrieved
Information about the creative type
GET https://sandbox.crm.com/self-service/v1/files/3ae9d64a-8a3b-f1e1-eed6-05b307f926fb HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
"mime": "doc"
}Ability to authenticate customers via a Mobile App or a Portal
{id}/wifi/authorization{id}/sign_out{token}Authenticate a contact and provide a token for subsequent API access
Request headers
The publishable api key for application identification
Request body
The contact’s identity provider
The contact’s username (applicable for EMAIL providers). If password not provided then OTP request is triggered.
The contact’s password (applicable for EMAIL providers)
The token taken from the oAUTH service provider (applicable for Facebook/Google/MW4 providers)
The contact’s device mac address (applicable for MAC_ADDRESS providers)
The contact’s phone number (applicable for PHONE providers)
The contact’s phone country code (applicable for PHONE providers)
The application identifier
Examples
Responses
The request has succeeded
Body
The token that can be used in subsequent API calls
Used when access token gets expired in order to refresh
The token expiration date
Details about the authorised contact
The cotnact’s unique identifier
The contact’s title
The contact’s first name
The contact’s last name
The contact’s company name
The contact’s avatar
Defines whether the used identity is verified
Details about the organisations that the contact has joined
The organisation’s external identifier
The organisation type
The organisation name
The input request was invalid or incorrect, often due to missing a required parameter
Auth using email and password
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"
}
]
}Auth using MAC Address
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": "MAC_ADDRESS",
"mac_address": "01-23-45-67-89-AB"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
"refresh_token": "",
"exp": "1572530655",
"contact": {
"id": "",
"title": "Mr",
"first_name": "John",
"last_name": "Doe",
"company_name": "",
"avatar": "avatar",
"is_verified": "false"
},
"organisations": [
{
"external_id": "QWERTY12345671234567324ETFTGBY78",
"org_type": "SERVICE_OWNER",
"name": "CRMdotCOM"
}
]
}Auth using MW4
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"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
"refresh_token": "",
"exp": "1572530655",
"contact": {
"id": "2f2f9afe-4399-59b7-cbb8-da18c2255064",
"title": "Mr",
"first_name": "John",
"last_name": "Doe",
"company_name": "CRM",
"avatar": "avatar",
"is_verified": "false"
},
"organisations": [
{
"external_id": "QWERTY12345671234567324ETFTGBY78",
"org_type": "SERVICE_OWNER",
"name": "CRMdotCOM"
}
]
}Auth using phone
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": "PHONE",
"phone_number": "22265566",
"country_code": "CYP"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
"refresh_token": "",
"exp": "1572530655",
"contact": {
"id": "2f2f9afe-4399-59b7-cbb8-da18c2255064",
"title": "Mr",
"first_name": "John",
"last_name": "Doe",
"company_name": "CRM",
"avatar": "avatar",
"is_verified": "false"
},
"organisations": [
{
"external_id": "QWERTY12345671234567324ETFTGBY78",
"org_type": "ORGANISATION",
"name": "CRMdotCOM"
}
]
}{id}/wifi/authorizationAuthenticate a contact over to a WiFi platform
Path variables
The contact (identifier) that will be authenticated over to a WiFi platform
Request headers
The publishable api key for application identification
Request body
The contat’s device MAC address
The usage estimation (identifier) that the contact is authorised for
The site that the contact is authorised against
Responses
The request has succeeded
The input request was invalid or incorrect, often due to missing a required parameter OR client has already signed in from anotyher device (ClientAlreadyAuthorizedException)
POST https://sandbox.crm.com/self-service/v1/contacts/eab82829-b65e-ee5a-b0f8-33b8ad48e04e/wifi/authorization HTTP/1.1
api_key: ab5f8b2e-092f-4848-8f46-31df1c014060
Content-Type: application/json
{
"integration_id": "6b6d31e9-3603-36e1-be89-76c1e538644b",
"mac_address": "01-23-45-67-89-AB",
"estimation_id": "0ba7de75-8a68-c19a-3d3a-f4708723a1a4"
}
HTTP/1.1 200 OK 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
The publishable api key for application identification
Request body
How to send the validation code
Information on how the contact will be identified
The predetermined information that will be used to identify the contact
Lookup on contact details
Lookup on contact details
Lookup on contact details
Lookup on contact customer identification medium (if enabled) and then on contact details
Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details
Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details
Lookup on customer identification medium (if enabled) and last on contact details
Lookup on customer identification medium (if enabled) and last on contact details
Lookup on contact identity
The value of the credential to check
Additional gift pass information. Applicable if name = “GIFT_PASS”
Email address which will receive the one-time-password, semi-optional - either email_address or phone_number must be provided
Phone number which will receive the one-time-password, semi-optional - either email_address or phone_number must be provided
The phone number country code (required for phone_number)
The gift pass pin, semi-optional - either pin or last_spend_amount must be provided
The last spend amount performed, semi-optional - either pin or last_spend_amount must be provided
Responses
The request has succeeded
Body
The obfuscated send method value
The one time password auth id
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"
}Request headers
The publishable api key for application identification
Request body
Information on how the contact will be identified
The predetermined information that will be used to identify the contact
Lookup on contact details
Lookup on contact details
Lookup on contact details
Lookup on contact customer identification medium (if enabled) and then on contact details
Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details
Lookup on contact identity, then on customer identification medium (if enabled) and last on contact details
Lookup on customer identification medium (if enabled) and last on contact details
The value of the credential to check
Responses
The request has succeeded
Verifies an one time password that was requested
Request headers
The publishable api key for application identification
Request body
Information on how the contact will be identified
Contact identification credentials
One Time Password Auth Id
The email address that was used to request the otp
The phone number that was used to request the otp
The contact’s id number that was used to request the otp
The contact’s passport that was used to request the otp
The contact’s birthdate that was used to request the otp
The contact’s card that was used to request the otp
The contact’s loyalty identifier that was used to request the otp
The value of the credential to verify the contact’s authenticity
The OTP that should be used for verification purposes
Examples
Responses
The request has succeeded
Body
The token that can be used in subsequent API calls
Used when access token gets expired in order to refresh
The token expiration date
Details about the authorised contact
The cotnact’s unique identifier
The contact’s title
The contact’s first name
The contact’s last name
The contact’s company name
The contact’s avatar
Defines whether the used identity is verified
Details about the organisations that the contact has joined
The organisation’s external identifier
The organisation type
The organisation name
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"
}
]
}Authenticate a contact and provide a token for subsequent API access
Request headers
Refresh Token supplied when authenticated
Responses
The request has succeeded
Body
The token that can be used in subsequent API calls
Used when access token gets expired in order to refresh
The token expiration date
Details about the authorised contact
The cotnact’s unique identifier
The contact’s title
The contact’s first name
The contact’s last name
The contact’s company name
The contact’s avatar
Defines whether the used identity is verified
Details about the organisations that the contact has joined
The organisation’s external identifier
The organisation type
The organisation name
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"
}
]
}Requests a password reset for an existing contact
Request headers
The publishable api key for application identification
Request body
The username that will be used to request a new password
Examples
Responses
The request has succeeded
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 Changes the password for a contact’s identity (EMAIL based)
Request body
The token that will verify that the client is trusted (required only if the identity is EMAIL based)
The new password
Examples
Responses
The request has succeeded
POST /contacts/change_password HTTP/1.1
Content-Type: application/json
{
"token": "ABCTKN123456798VGP2020",
"password": "wsxcde421qadfg"
}
HTTP/1.1 200 OK {id}/sign_outTerminates the contact’ session and will no longer be able to access the client
Path variables
The contact (identifier) that will be signed out
Request headers
Authorization Token
Responses
The request has succeeded
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/sign_out HTTP/1.1
Authorization: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK {token}Verify a contact’s email address username
Path variables
The token that will used for verifying the contact’s email address
Responses
The request has succeeded
GET https://sandbox.crm.com/self-service/v1/contacts/verify_email/ABCTKN123456798VGP2020 HTTP/1.1
HTTP/1.1 200 OK {id}/communications{id}{id}/actions{id}/communicationsGet a list of a contact’s communications
Path variables
The contact (identifier) for which the related communications will be retrieved
Request parameters
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
The type of the communications to be retrieved
If set to TRUE, only archived communications will be retrieved
If set to TRUE, only viewed communications will be retrieved
Request headers
Authorization Token
Responses
The request has succeeded
Body
Information about the retrieved communication records
The communication identifier
The state of the communication
The contact identifier that communication was sent to
The channel that the communication is sent through
Defines whether the communication has been viewed
The datetime that the recipient viewed the communication
Defines whether the communication has been archived
The date links in the communication where first clicked by the recipient
The language tha the communication was sent in
The default sender
The email or number of the recipient
The actual subject of the communication sent (if applicable)
The actual content of the communication sent
The name of the communication plan in case the communication was created from a plan
Information that can be used in order to display large pages
The page number
The number of records per page
The total number of records
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
}
}{id}Get a specific contact’s communication
Path variables
The communication identifier that should be returned
Request headers
Authorization Token
Responses
The request has succeeded
Body
The state of the communication
Details about the communication contact
The unique identifier of the contact
The full name of the contact
The unique code of the contact
The channel that the communication is sent through
Defines whether the communication has been viewed
The datetime that the recipient viewed the communication
Defines whether the communication has been archived
The date links in the communication where first clicked by the recipient
The language tha the communication was sent in
The default sender
The communication’s recipient information
The actual subject of the communication sent (if applicable)
The actual content of the communication sent
The name of the communication plan in case that the communication was created based on a plan
The date and time that the communication was created
Title of push notification (applicable for INAPP channels)
Subtitle (iOS only) of push notification (applicable for INAPP channels)
Image for push notification
Push notification URL (deep linking)
GET https://sandbox.crm.com/self-service/v1/communications/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
auth_token: 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,
"title": "New Festive Beverages",
"subtitle": "20% discount for December",
"in_app_image_url": "",
"in_app_click_link_url": ""
}{id}/actionsMark an existing communication as viewed and/or archived
Path variables
The communication identifier
Request headers
Authorization Token
Request body
Sets the communication as viewed
Sets the communication as archived
Responses
The request has succeeded
Body
The communication identifier
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"
}Request (and retrieve) a printout for an invoice or order
Notes
Integrating printout export for Contacts should be based on the following APIs
Request headers
Authorization Token
Request body
Defines the format on which the printout will be created to
Printout will be generated as pdf
Printout will be sent to the contact’s email address
Defines the entity based on which the printout will be created
The entity type
The entity identifier
Responses
The request has succeeded (applicable if printout is PDF based)
Body
The printout identifier that will be exported
The request has succeeded (applicable if printout is EMAIL based)
POST https://sandbox.crm.com/self-service/v1/printout HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
Content-Type: application/json
{
"format": "PDF",
"entity": {
"type": "INVOICE",
"id": "b97d4488-e9c1-a338-8420-b831147b648f"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "e1c67e12-6bae-53c7-f1a1-0a26aa4b27a2"
}Contact Management
{id}{id}{id}/consents{id}{id}/demographics{id}/preferences{id}/preferencesCreate a new contact (of type person)
Request headers
The publishable api key for application identification
Request body
The contact first name (required for EMAIL and PHONE providers)
The contact last name (required for EMAIL and PHONE providers)
Details about the customer’s identity
The contact’s identity provider
The contact’s username (required for EMAIL). If password not provided then OTP request is triggered.
The contact’s password (applicable for EMAIL).
Defines whether the email requires verification (applicable when username and password are provided)
The contact’s phone number (required for PHONE). OTP request is triggered.
The contact’s phone number country code (required for PHONE)
Application ID requesting register
The token taken from the oAUTH service provider (required for Facebook and Google)
Defines whether the contact has accepted the client service
The contact setting for receiving emails
The contact setting for receiving sms
The contact setting for consent
The code that the contact was referred with in order to register
The country code that the contact agreed to register to
The custom field’s unique key
The custom field’s value
Pass code to be redeemed - optionally used on Landing page registration flow, if pass code is invalid then contact registration will not proceed
Examples
Responses
The request has succeeded
Body
The token that can be used in subsequent API calls
The token expiration date
Details about the authorised contact
The contact’s title
The contact’s first name
The contact’s last name
The contact’s avatar
Defines whether the used identity is verified
Details about the organisations that the contact has joined
The organisation’s external identifier
The organisation type
The organisation relationship
The organisation name
The obfuscated send method value (applicable only when provider is EMAIL or PHONE and an OTP is generated)
The one time password auth id (applicable only when provider is EMAIL or PHONE and an OTP is generated)
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"
}Contact registration including a pass code from a Landing page
POST https://sandbox.crm.com/self-service/v1/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": "2265577",
"country_code": "CYP",
"application_id": "3c33dcc6-3958-4e7d-ae0e-592948627711",
"token": "YOJDAKEb9l1U0sUzrskM6X4emzrSeXqb"
},
"pass_code": "HHNSU32LNK"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
"exp": "1572530655",
"contact": {
"first_name": "John",
"last_name": "Doe",
},
"organisations": [
{
"external_id": "QWERTY12345671234567324ETFTGBY78",
"org_type": "ORGANISATION",
"org_relationship": "MERCHANT",
"name": "CRMdotCOM"
}
],
"obfuscated_value": "+35799***834",
}{id}Unregisters a contact from an organisation
Path variables
The id of the contact to unregister
Request headers
Authorization Token
Responses
The request has succeeded
Remove an existing contact address
DELETE https://sandbox.crm.com/self-service/v1/contacts/e18ee2bc-c6f3-49e1-8e05-763386378017 HTTP/1.1
auth_token: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK {id}Updates an existing contact
Path variables
The contact (identifier) that will be updated
Request headers
Authorization Token
Request body
Company Name if the Contact represents a company, required attribute if the type is a Company.
The title of the contact. Applicable only if the type is PERSON
The first name of the contact. Applicable and mandatory only if the type is PERSON
The middle name of the contact. Applicable and mandatory only if the type is PERSON
The last name of the contact. Applicable and mandatory only if the type is PERSON
The contact preferred language
The contact’s category ID
The contact statutory number
Information about the person demographics
The person gender
Information about the person passport
The passport number
The country that issued the passport
The passport expiration date
Information about the person id
The id number
The country that issued the id
The id expiration date
Information about the person nameday
The nameday month
The nameday day
Information about the person birthdate
The birth year
The birth month
The birth day
A company’s profile. Applicable only if contact_type is COMPANY
The company’s profile year
The annual turnover
The date that the company was established on
The company’s number of employees
The company registration number
The country that the company is registered to
The company tax reference number
The company vat registration number
The company’s Industry ID
The company’s Industry Sectors.
The contact’s email address
The contact setting for receiving sms
The contact setting for receiving email
Defiens whether the contact is tax exempt or not
The custom field’s unique key
The custom field’s value
Responses
The request has succeeded
Body
The contact identifier
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"
}{id}/consentsUpdates the Consent state of the Contact
Path variables
The contact identifier that will be updated
Request headers
Authorization Token
Request body
The contact setting for consent
Responses
The request has succeeded
Body
The contact identifier
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"
}{id}Retrieve basic details for a specific contact
Path variables
The contact identifier that should be returned
Request headers
Authorization Token
Responses
The request has succeeded
Body
The contact identifier
The contact code
Tje contact type
The contact title
The contact first name
The contact middle name
The contact last name
The contact preferred language
The contact URL of Avatar
The contact email address