BackOffice Admin

Introduction

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

The CRM.COM API is designed around REST, allowing you to access and extend the software’s current functionality in a simple, programmatic way using intuitive URL endpoints, conventional HTTP requests, response codes, authentication and verbs.

Back-Office API is designed with a main focus on back-office users and external systems that desire to access and extend the functionality found in CRM.COM.

For the Mobile/Web based Applications API please refer to the Self-Service API documentation that provides more details how to allow customer to manage their subscriptions and/or reward accounts.

Authentication

CRM.COM API uses either API keys to authenticate requests, or an authentication JWT token obtained from a user logging in successfully.

You can view and manage your API keys in the CRM.COM Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth.

-H “api_key : crm_test_;dwfwgiuhjr412edws”

If you need to authenticate a Admin User bearer auth, use -H “Authorization: Bearer JWT_TOKEN”

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

API requests without authentication will also fail.

Unique Resource Identifiers

CRM.COM is built on a domain based micro-service architecture. Our primary resources such as Contact, Account, Wallet, Products, Subscriptions are all created with a unique identifier that uses a performant time based GUID. These are generated when a new resource such as a contact is created. However in some cases external integration may wish to use a unique identfier that is stored in an external system, such as a Bank CIF or Credit Card fingerprint.

Some systems allow from their create APIs to supply a unique identifier as part of the request body. CRM.COM has decided to provide an alternative approach and make an alternative unique identifier available on resources (e.g. on Contacts we provide the contact.code). If such attribute is specified during the create operation it wil be available on subsequent operations as a resource’s identifier, alongside with the GUID that is returned in the response body. Updating such resource can be achieved either using PUT /contact/GUID or PUT /contact/CODE.

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 200

The request has succeeded

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Operations
Contacts
POST /contacts
PUT /contacts/{id}
PUT /contacts/
PUT /contacts/{id}/consents
Create Contact
POST /contacts

Create a new contact, either a new Person or a Company

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID

The contact identifier, if not supplied one will be generated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

User readable code for the contact

Example:
ABC-123
contact_type
string required

Type of contact support types include Person and Company.

Enumeration:
PERSON
COMPANY
company_name
string required nullable

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

Example:
Good Burger
title
string

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

Example:
Sir
first_name
string required nullable

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

Example:
Louis
middle_name
string nullable

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

Example:
Aloz
last_name
string required nullable

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

Example:
Kozior
preferred_language_code
string

The contact’s preferred language for communication

Example:
ENG
statutory_number
string

The contact’s unique statutory number

Example:
231224-1222000
notes
string

Notes for the contact

Example:
Notes
direct_marketing
boolean nullable

The contact authorisation setting for direct marketing

Example:
true
affiliate_marketing
boolean nullable

The contact authorisation setting for affiliate marketing

Example:
false
create_default_account
boolean

If set to true, then a single account is created for the contact usig the system’s default settings and no further input is needed.

Example:
true
category
Object

The contact’s category. The category’s ID or code should be specified

id
string GUID

The category’s GUID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The category’s code

Example:
ABC-123
demographics
Object

Information about the contact’s demographic. Applicable only if the contact type is PERSON

gender
string

The gender of the contact

Enumeration:
MALE
FEMALE
country_of_residence
string

The country code for the country of residence

Example:
USA
passport
Object

Information about the contact’s passport

passport_number
string

The passport number

Example:
K)123456
issue_country_code
string

The passport’s issue country code

Example:
GRC
expiration_date
number epoch

The passport’s expiration date

Example:
129876564
id_details
Object

Information about the contact’s id. Applicable only if the contact is type of PERSON

id_number
string

The id number

Example:
132465
issue_country_code
string

The id’s issue country code

Example:
CYP
expiration_date
integer epoch

The id’s expiration date

Example:
1129876567
name_day
Object

The contact’s name day. Applicable only if the contact is type of PERSON

month
integer

The month of the name day

Example:
4
day
integer

The day of the name day

Example:
12
date_of_birth
Object

Information about the contact’s data of birth. Applicable only if the contact is type of PERSON

year
integer

The birtdate year

Example:
1999
month
integer

The borthdate month

Example:
12
day
integer

The borthdate day

Example:
31
company_profile
Object

Information about the company’s profile. Applicable only if contact_type is COMPANY

industry
Object

The company’s Industry. Either the id or the code should be specified.

id
string GUID

The industry’s identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The industry’s code

Example:
IT
industry_sectors
Array

The company’s industry sectors. Multiple industry sector can be specified. Either the id or the code should be specified for each sector

Object
id
string GUID

The industry sector’s identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The industry sector’s code

Example:
INDS1234
profile_year
integer

The profile year

Example:
2019
annual_turnover
integer

The annual turnover

Example:
450000
established_on
integer epoch

The date that the company was established on

Example:
98765342
number_of_employees
integer

The company’s number of employees

Example:
200
registration_number
string

The company’s registration number

Example:
123456
registration_country
string

The company’s registrationc country code

Example:
CYP
tax_reference_number
string

The company’s tax reference number

Example:
TAX1234
vat_registration_number
string

The company VAT registration numnber

Example:
VAT1234
addresses
Array nullable

Information about the contact’s addresses

Object
address_type
string required

The address type

Enumeration:
HOME
BUSINESS
POBOX
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
is_primary
boolean

Primary address for Billing or Communication

Example:
true
care_of
string
address_line_1
string
address_line_2
string
Example:
Thomas V
state_province_county
string
Example:
Active
town_city
string
postal_code
string
country_code
string
Example:
CYP
phones
Array
Object
phone_type
string required
Enumeration:
LANDLINE
MOBILE
FAX
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
is_primary
boolean
Example:
true
country_code
string
Example:
CYP
number
string
Example:
238065437
emails
Array
Object
email_type
string required
Enumeration:
PERSONAL
BUSINESS
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
is_primary
boolean
Example:
true
email_address
string
Example:
johndoe@crm.com
accounts
Array

Optional basic account settings for a financial contact

Object
name
string

The account name

is_primary
boolean

Indicates the primary account of the contact

credit_rating
string

The account’s credit rating

Enumeration:
AAA
AA
A
BAA
BA
B
CAA
CA
C
credit_limit
number

The account’s credit limit

Example:
250
currency_code
string

The account’s currency

Example:
GBP
is_tax_exempt
boolean

Defines whether the account is TAX exempt

Example:
true
classification
Object

The account’s Classification

id
string GUID

The account classification identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The account classification’s code

Example:
VIP
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
Example 2

Create a contact for a physical person

POST /contacts HTTP/1.1 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "ABC-123",
    "contact_type": "PERSON",
    "title": "Sir",
    "first_name": "Louis",
    "middle_name": "Aloz",
    "last_name": "Kozior",
    "preferred_language_code": "ENG",
    "statutory_number": "231224-1222000",
    "notes": "Notes",
    "direct_marketing": "true",
    "affiliate_marketing": "false",
    "create_default_account": true,
    "category": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "code": "ABC-123"
    },
    "demographics": {
        "gender": "MALE",
        "country_of_residence": "USA",
        "passport": {
            "passport_number": "K)123456",
            "issue_country_code": "GRC",
            "expiration_date": 129876564
        },
        "id_details": {
            "id_number": "132465",
            "issue_country_code": "CYP",
            "expiration_date": 1129876567
        },
        "name_day": {
            "month": 4,
            "day": 12
        },
        "date_of_birth": {
            "year": 1999,
            "month": 12,
            "day": 31
        }
    },
    "addresses": [
        {
            "address_type": "POBOX",
            "is_primary": "true",
            "care_of": "",
            "address_line_1": "",
            "address_line_2": "Thomas V",
            "state_province_county": "Active",
            "town_city": "",
            "postal_code": "",
            "country_code": "CYP"
        }
    ],
    "phones": [
        {
            "phone_type": "CUSTOM2",
            "is_primary": true,
            "country_code": "CYP",
            "number": "238065437"
        }
    ],
    "emails": [
        {
            "email_type": "PERSONAL",
            "is_primary": true,
            "email_address": "johndoe@crm.com"
        }
    ],
    "accounts": [
        {
            "name": "",
            "is_primary": true,
            "credit_rating": "AA",
            "credit_limit": 250,
            "currency_code": "GBP",
            "is_tax_exempt": true,
            "classification": {
                "id": "",
                "code": "VIP"
            }
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

Create a contact for a company

POST /contacts HTTP/1.1 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "ABC-123",
    "contact_type": "COMPANY",
    "company_name": "Good Burger",
    "preferred_language_code": "ENG",
    "statutory_number": "231224-1222000",
    "notes": "Notes",
    "direct_marketing": "true",
    "affiliate_marketing": "false",
    "create_default_account": true,
    "category": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "code": "ABC-123"
    },
    "company_profile": {
        "industry": {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "code": "IT"
        },
        "industry_sectors": [
            {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "code": "INDS1234"
            }
        ],
        "profile_year": 2019,
        "annual_turnover": 450000,
        "established_on": 98765342,
        "number_of_employees": 200,
        "registration_number": "123456",
        "registration_country": "CYP",
        "tax_reference_number": "TAX1234",
        "vat_registration_number": "VAT1234"
    },
    "addresses": [
        {
            "address_type": "HOME",
            "is_primary": "true",
            "care_of": "",
            "address_line_1": "",
            "address_line_2": "Thomas V",
            "state_province_county": "Active",
            "town_city": "",
            "postal_code": "",
            "country_code": "CYP"
        }
    ],
    "phones": [
        {
            "phone_type": "CUSTOM4",
            "is_primary": true,
            "country_code": "CYP",
            "number": "238065437"
        }
    ],
    "emails": [
        {
            "email_type": "CUSTOM3",
            "is_primary": true,
            "email_address": "johndoe@crm.com"
        }
    ],
    "accounts": [
        {
            "name": "",
            "is_primary": true,
            "credit_rating": "B",
            "credit_limit": 250,
            "currency_code": "GBP",
            "is_tax_exempt": true,
            "classification": {
                "id": "",
                "code": "VIP"
            }
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Update Contact
PUT /contacts/{id}

Update A Contact, it is possible to supply a partial body so that only supplied items will be updated.

Path variables

id
string required

internal Unique ID of Contact as specified on request or response of create

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
code
string

The contact’s unique code

Example:
ABC-123
company_name
string

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

Example:
Good Burger
title
string

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

Example:
Sir
first_name
string

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

Example:
Louis
middle_name
string

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

Example:
Aloz
last_name
string

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

Example:
Kozior
preferred_language_code
string
Example:
ENG
category
Object

The contact’s category. Either id or code should be specified

id
string

The contact category GUID

code
string

The cotnact category code

Example:
VIP
notes
string
Example:
Notes
statutory_number
string
Example:
EF12345
demographics
Object
gender
string
Enumeration:
MALE
FEMALE
country_of_residence
string
passport
Object
passport_number
string
issue_country_code
string
Example:
GRC
expiration_date
integer
Example:
129876567
id_details
Object
id_number
string
isssue_country_code
string
Example:
CYP
expiration_date
integer
name_day
Object
month
integer
Example:
10
day
integer
Example:
4
date_of_birth
Object
year
integer
Example:
2018
month
integer
Example:
10
day
integer
Example:
16
company_profile
Object

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

industry
Object

The company’s Industry. Either id or code should be specified

id
string

The industry’s GUID

code
string

The industry’s code

industry_sectors
Array

The company’s Industry Sectors. Either id or code should be specified per industry sector

Object
id
string
Example:
45345345345
code
string
profle_year
number
annual_turnover
number
established_on
integer
number_of_employees
number
registration_number
string
registration_country
string
tax_reference_number
string
vat_registration_number
string
addresses
Array
Object
id
string
address_type
string
Enumeration:
HOME
BUSINESS
POBOX
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
care_of
string
is_primary
string
Example:
true
address_line_1
string required
address_line_2
string
Example:
Thomas V
state_province_county
string
Example:
California
town_city
string
postal_code
string
country_code
string
Example:
CYP
phones
Array
Object
id
string
phone_type
string
Enumeration:
LANDLINE
MOBILE
FAX
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
is_primary
boolean
Example:
true
country_code
string
Example:
44
number
string
Example:
238065437
emails
Array
Object
id
string
email_type
string
Enumeration:
BUSINESS
PERSONAL
CUSTOM1
CUSTOM2
CUSTOM3
CUSTOM4
CUSTOM5
is_primary
boolean
Example:
true
email_address
string
Example:
bill@gmail.com
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

Body
Object
id
string

The updated contact’s GUID

Example:
GUID
Examples
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
PUT /contacts/{id} HTTP/1.1 

Content-Type: application/json

{
    "code": "ABC-123",
    "title": "Sir",
    "first_name": "Louis",
    "middle_name": "Aloz",
    "last_name": "Kozior",
    "preferred_language_code": "ENG",
    "category": {
        "id": "",
        "code": "VIP"
    },
    "notes": "Notes",
    "statutory_number": "EF12345",
    "demographics": {
        "gender": "FEMALE",
        "country_of_residence": "",
        "passport": {
            "passport_number": "",
            "issue_country_code": "GRC",
            "expiration_date": 129876567
        },
        "id_details": {
            "id_number": "",
            "isssue_country_code": "CYP",
            "expiration_date": 1
        },
        "name_day": {
            "month": 10,
            "day": 4
        },
        "date_of_birth": {
            "year": 2018,
            "month": 10,
            "day": 16
        }
    },
    "addresses": [
        {
            "id": "",
            "address_type": "CUSTOM2",
            "care_of": "",
            "is_primary": "true",
            "address_line_1": "",
            "address_line_2": "Thomas V",
            "state_province_county": "California",
            "town_city": "",
            "postal_code": "",
            "country_code": "CYP"
        }
    ],
    "phones": [
        {
            "id": "",
            "phone_type": "CUSTOM2",
            "is_primary": true,
            "country_code": "44",
            "number": "238065437"
        }
    ],
    "emails": [
        {
            "id": "",
            "email_type": "CUSTOM3",
            "is_primary": true,
            "email_address": "bill@gmail.com"
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Bulk Update Contact
PUT /contacts/

Update multiple contacts in bulk mode. Available from CRM.COM R18.2.0

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
contacts
Array

A list containing the contacts to be updated. Either the id or the code mus tbe speficied in each Web API call

Object
contact
Object required

The contact to be updated. Either the id or the code should be specified

id
string GUID

The contact’s GUID

Example:
3452AB543FF03
code
string

The contact’s code

Example:
ABC-12345
category
Object
id
string GUID

The category’s unique identifier

Example:
3420001ADF354
code
string

The cateogry’s code

Example:
VIP
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

Body
Object
id
string

A unique identifier of the Web API call which can be used for triggering the webhook and relate the api request to the webhook request (enables integrator to match the api request with the webhook request).

Example 1
PUT /contacts/ HTTP/1.1 

Content-Type: application/json

{
    "contacts": [
        {
            "contact": {
                "id": "3452AB543FF03",
                "code": "ABC-12345"
            },
            "category": {
                "id": "3420001ADF354",
                "code": "VIP"
            },
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
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

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
consent_state
string

The consent state to be updated

Enumeration:
PENDING
ACCEPTED
REJECTED
WITHDRAWN

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the contact

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

Content-Type: application/json

{
    "consent_state": "WITHDRAWN"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Credentials
POST /contacts/{id}/credentials
Add authorisation credentials to existing Contact
POST /contacts/{id}/credentials

Create a set of credentials for an existing customer

Path variables

id
string GUID required

The contact that should be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
username
string required

The contact’s username

Example:
j_doe@crm.com
password
string required

The contact’s password

Example:
12345

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The credentials identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

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

{
    "username": "j_doe@crm.com",
    "password": "12345"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Contacts Financial Operations
GET /vouchers
GET /contacts/{id}/wallet_transactions
POST /vouchers/{id}
POST /vouchers/{id}/expiration_date
POST /contacts/{id}/wallet_transactions/{transaction_id}
List Vouchers
GET /vouchers

Retrieves the available vouchers

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
classification
string optional

The voucher classification

Enumeration:
PRINTED
ELECTRONIC
REFUND
life_cycle_state
string optional

The voucher’s life cycle state

Enumeration:
DRAFT
ACCEPTED
NOT_ACCEPTED
ACTIVATED
USED
CANCELLED
PURGED
type_id
string GUID optional

The type of the vouchers to be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E
category
string optional

The vouchers category

Enumeration:
NORMAL
IDENTIFIES_CUSTOMER
number
string optional

The number of the voucher to be retrieved

Example:
V123456

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

OK

Body
Object
id
string GUID

The voucher identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
contact_id
string GUID

The contact that owns the voucher

Example:
6A24D2B5E44F44B28451FE021FCAD51E
number
string

The voucher number

Example:
V0123456
classification
string

The voucher classification

Enumeration:
PRINTED
ELECTRONIC
REFUND
life_cycle_state
string

The life cycle state of the voucher

Enumeration:
DRAFT
ACCEPTED
NOT_ACCEPTED
ACTIVATED
USED
CANCELLED
PURGED
category
string

The vouchers category

Enumeration:
NORMAL
IDENTIFIES_CUSTOMER
value
number

The value of the voucher. Can be empty

Example:
200
extra_added_value
number

An extra added value of the voucher. Can be empty

Example:
10
minimum_value
number

The minimum value allowed for the voucher (if value is empty)

Example:
50
maximum_value
number

The maximum value allowed for the voucher (if value is empty)

validity_period
integer

The number of UOT that the voucher amount will be valid for

Example:
1
validity_UOT
string

The UOT that the voucher amount will be valid for

Enumeration:
DAY
MONTH
YEAR
expiration_date
string epoch

The actual expiration date of the voucher

Example:
1585040255
paging
Array
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The total number of records overall

Example:
5214
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
GET /vouchers HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "contact_id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "number": "V0123456",
    "classification": "REFUND",
    "life_cycle_state": "ACTIVATED",
    "category": "IDENTIFIES_CUSTOMER",
    "value": 200,
    "extra_added_value": 10,
    "minimum_value": 50,
    "maximum_value": 1,
    "validity_period": 1,
    "validity_UOT": "YEAR",
    "expiration_date": "1585040255",
    "paging": [
        {
            "page": 2,
            "size": 20,
            "total": 5214
        }
    ]
}
List Wallet Transactions
GET /contacts/{id}/wallet_transactions

Retrieves the wallet transactions of a specific contact

Path variables

id
string GUID required

The contact identifier whose wallet transactions will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
transaction_date
integer epoch optional

The date that the retrieved wallet transactions were created

Example:
1584976326
classification
string optional

The wallet transaction classification

Enumeration:
DEBIT
CREDIT
TRANSFER
REIMBURSE
VOID
life_cycle_state
string optional

The wallet transaction life cycle state

Enumeration:
EFFECTIVE
VOIDED

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

OK

Body
Object
id
string GUID

The wallet transaction identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
account_id
string

The accout owner’s GUID

Example:
6A24D2B5E44F44B28451FE021FCAD52E
wallet_id
string GUID

The wallet of the transaction

Example:
6A24D2B5E44F44B28451FE021FCAD51E
number
string

The wallet transaction number

Example:
WT123456
classification
string

The wallet transaction classification

Enumeration:
CREDIT
DEBIT
REIMBURSE
TRANSFER
VOID
life_cycle_state
string

The life cycle state of the wallet transaction

Enumeration:
EFFECTIVE
VOID
amount
number

The amount of the wallet transaction in system currency

Example:
200
extra_added_amount
number

An extra added amount in wallet currency

transaction_date
string epoch

The date that the wallet transaction was made

Example:
1573545935
expiration_date
string epoch

The wallet transaction expiration date

Example:
1573545935
created_by
Object

The user that created the wallet transaction

id
string GUID

The unique identifier of the user

Example:
6A24D2B5E44F44B28451FE021FCAD51E
created_on
string epoch

The date and time that the wallet transaction was created

Example:
1573545935
paging
Array
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The total number of records overall

Example:
5124
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
    "wallet_id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "number": "WT123456",
    "classification": "TRANSFER",
    "life_cycle_state": "VOID",
    "amount": 200,
    "extra_added_amount": 1,
    "transaction_date": "1573545935",
    "expiration_date": "1573545935",
    "created_by": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E"
    },
    "created_on": "1573545935",
    "paging": [
        {
            "page": 2,
            "size": 20,
            "total": 5124
        }
    ]
}
Use Voucher
POST /vouchers/{id}

Uses a single voucher

Path variables

id
string GUID required

The unique identifier of the voucher to be used

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
secret_number
string required

The secret number of the voucher to be used

Example:
S0123456
value
number

The value of the voucher to be used. Applicable only if the voucher type allows variable values

Example:
200
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

Body
Object
id
string GUID

The used voucher ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /vouchers/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "secret_number": "S0123456",
    "value": 200,
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Update Voucher Expiration Date
POST /vouchers/{id}/expiration_date

Path variables

id
string required

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
expiration_date
string epoch

The new expiration date of the voucher

Example:
1585040255

Responses

200 OK

OK

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /vouchers/{id}/expiration_date HTTP/1.1 

Content-Type: application/json

{
    "expiration_date": "1585040255"
}

HTTP/1.1 200 OK 
Void Wallet Transaction
POST /contacts/{id}/wallet_transactions/{transaction_id}

Voids a single wallet transaction

Path variables

id
string GUID required

The unique identification of the contact owning the wallet transaction

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
transaction_id
string GUID required

The unique identification of the wallet transaction to be voided

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

Content-Type: application/json

{
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Contact Wallet
POST /wallets/debits
POST /wallets/{id}/cancel
GET /contacts/{id}/wallets
POST /wallets/adjust
Debit Wallet
POST /wallets/debits

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID required nullable

The wallet’s GUID

Max length: 32
Example:
6A24D2B5E44F44B28451FE021FCAD51E
account_id
string GUID required nullable

The accout owner’s GUID

Max length: 32
Example:
6A24D2B5E44F44B28451FE021FCAD52E
voucher_number
string required nullable

The voucher of type identifies customer that will be used to credit the wallet and then identify the wallet and debit it

Example:
V0123456
secret_number
string

In case that the identification is a voucher then the secret number may be required

Example:
1234
amount
number float required

The amount to be debited

Example:
1234.56
type
string GUID nullable

The type of the debit wallet transaction

Max length: 32
Example:
6A24D2B5E44F44B28451FE021FCAD52E
allotments
Object
consumption_date
integer EPOCK nullable

The consumption validity date for the allotted amount. If not specifried the current date is used.

Example:
1578580663
product_identifier
string GUID nullable

The product related with the wallet transaction allotment

Max length: 32
Example:
6A24D2B5E44F44B28451FE021FCAD52E
business_unit_identifier
string GUID nullable

The business unit related with the wallet transaction allotment

Max length: 32
Example:
6A24D2B5E44F44B28451FE021FCAD52E
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

Body
Object
id
string GUID

The ID of the wallet transaction created

Example:
6A24D2B5E44F44B28451FE021FCAD52E
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /wallets/debits HTTP/1.1 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
    "voucher_number": "V0123456",
    "secret_number": "1234",
    "amount": 1234.56,
    "type": "6A24D2B5E44F44B28451FE021FCAD52E",
    "allotments": {
        "consumption_date": 1578580663,
        "product_identifier": "6A24D2B5E44F44B28451FE021FCAD52E",
        "business_unit_identifier": "6A24D2B5E44F44B28451FE021FCAD52E"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Cancel Wallet
POST /wallets/{id}/cancel

Cancels a single wallet

Path variables

id
string GUID required

The wallet identifier to be cancelled

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /wallets/CAD1E31269B76D7A65ACCE45B2E68DFD/cancel HTTP/1.1 

Content-Type: application/json

{
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
List Wallets
GET /contacts/{id}/wallets

Retrieves the wallets of a specific contact

Path variables

id
string GUID required

The contact identifier whose wallets will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

OK

Body
Object
id
string GUID

The wallet identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
account_id
string

The accout owner’s GUID

Example:
6A24D2B5E44F44B28451FE021FCAD52E
number
string
Example:
W000001
balance
number
Example:
1234.56
alternative_balance
number
Example:
231.54
currency_code
string
Example:
EUR
alternative_currency_code
string
Example:
PTS
conditional_balance
number
Example:
25.34
conditional_alternative_balance
number
Example:
1.52
unconditional_balance
number
Example:
4.75
unconditional_alternative_balance
number
Example:
4.57
amount_on_hold
number
Example:
5.98
alternative_amount_on_hold
number
Example:
2.34
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
    "number": "W000001",
    "balance": 1234.56,
    "alternative_balance": 231.54,
    "currency_code": "EUR",
    "alternative_currency_code": "PTS",
    "conditional_balance": 25.34,
    "conditional_alternative_balance": 1.52,
    "unconditional_balance": 4.75,
    "unconditional_alternative_balance": 4.57,
    "amount_on_hold": 5.98,
    "alternative_amount_on_hold": 2.34
}
Adjust Wallet
POST /wallets/adjust

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID required nullable

The wallet’s GUID

Example:
6A24D2B5E44F44B28451FE021FCAD51E
classification
string

The wallet transaction classification

Enumeration:
CREDIT
DEBIT
amount
number float required

The amount to be credited or debited

Example:
123.45
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 OK
Body
Object
id
string GUID

The ID of the wallet transaction created

Example:
6A24D2B5E44F44B28451FE021FCAD52E
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /wallets/adjust HTTP/1.1 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "classification": "CREDIT",
    "amount": 123.45,
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Payment Methods
POST /contacts/{id}/payment_methods
DELETE /contacts/{id}/payment_methods/{payment_method_id}
GET /contacts/{id}/payment_methods
Add Payment Method
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 required

The contact identifier (GUID) or code that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID

The payment method identifier, if not specified it will be auto generated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
payment_method_type
string required

The payment method’s type

Enumeration:
BANK
CARD
PAYPAL
notes
string
Example:
some notes
bank_details
Object

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

account_holder_name
string
Example:
John Doe
account_number
string

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

Example:
001002001
iban
string

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

Example:
0143240434320434
sort_code
string
Example:
20-02-53
bank
string
Example:
Barclays
branch
string
Example:
Ascot
swift
string
Example:
12345678
card
Object

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
default card
brand
string

The card’s brand

Enumeration:
VISA
MASTERCARD
AMERICANEXPRESS
DINERSCLUB
DISCOVER
JCB
UNIONPAY
UNKOWN
card_number
string

The Card number.

Example:
492942******7004
first6
string

The first 6 digits of the card.

last4
string

The last 4 digits of the card.

fingerprint
string

Encrypted hashed version of the card for comparison only as a CIM

Example:
Xt5EWLLDS7FJjR1c
expiration_month
integer required
Example:
1
expiration_year
integer required
Example:
2020
is_default
boolean
Example:
true
card_holder_details
Object
card_holder_name
string required
Example:
Mrs M Smith
address_line_1
string
Example:
address_line_1
address_line_2
string
Example:
address_line_2
address_city
string
Example:
address_city
address_zip
string
Example:
address_zip
address_state
string
Example:
address_state
address_country
string
Example:
address_country
use_billing_address
boolean

If set to True, then the card holder’a address is automatically set using the account’s billing address

Example:
false
card_gateway_token
Array
Object
gateway
string

The payment gateway that tokenized the card

Example:
STRIPE,BRAINTREE,PAYEEZY,GENERIC
gateway_code
string

If using the Generic Gateway specify the implementation code given to you by CRM.COM

token
string required

The card token

Example:
123434556232134324
payment_gateway
Object

Use a payment gateway with an account such as PAYPAL. Required and applicable if payment method is set to PAYPAL

gateway
string required
Example:
PAYPAL
username
string required
Example:
bill@gmail.com

Responses

200 200

OK

Body
Object
id
string GUID

The payment method identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

Add a Card payment method

POST /contacts/423423424234/payment_methods HTTP/1.1 

Content-Type: application/json

{
    "id": "34234234-34343",
    "payment_method_type": "CARD",
    "notes": "some notes",
    "card": {
        "name": "default card",
        "brand": "AMERICANEXPRESS",
        "card_number": "492942******7004",
        "first6": "",
        "last4": "",
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "expiration_month": 1,
        "expiration_year": 2020,
        "is_default": true,
        "card_holder_details": {
            "card_holder_name": "Mrs M Smith",
            "address_line_1": "address_line_1",
            "address_line_2": "address_line_2",
            "address_city": "address_city",
            "address_zip": "address_zip",
            "address_state": "address_state",
            "address_country": "address_country",
            "use_billing_address": "false"
        },
        "card_gateway_token": [
            {
                "gateway": "STRIPE,BRAINTREE,PAYEEZY,GENERIC",
                "gateway_code": "",
                "token": "123434556232134324"
            }
        ]
    }
}
Remove Payment Method
DELETE /contacts/{id}/payment_methods/{payment_method_id}

Removes a single payment method from the contact

Path variables

id
string GUID required

The contact identifier whose payment method will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
payment_method_id
string GUID required

The payment method identifier that will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

OK

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
DELETE /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/payment_methods/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 
List Payment Methods
GET /contacts/{id}/payment_methods

List of Payment method allocated to subscriber.

Path variables

id
string required

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The payment method identifier

Example:
f21abc565467897543bcdefa12
bank
Array
Object
sort_code
string
Example:
20-02-53
account_number
string
Example:
001002001
bank
string
Example:
Barclays
branch
string
Example:
Ascot
iban
string
Example:
0143240434320434
payment_method_type
string
Enumeration:
DIRECT_DEBIT
CARD
PAYPAL
payment_gateway_token
string

The username of the payment gateway token for Paypal payment methods

Example:
anemail@email.com
card
Object

The basic card information for Card payment methods

brand_name
string

The card’s brand name

Enumeration:
VISA
MASTERCARD
AMERICANEXPRESS
DINERSCLUB
DISCOVER
JCB
UNIONPAY
UNKNOWN
card_number
string

Masked card number

last4
string

The last four digits of the card

funding_type
string

The card’s funding type. Available from CRM.COM-R18.2.0

Enumeration:
DEBIT
CREDIT
PREPAID
classification
Object

The card’s classification. Available from CRM.COM R18.2.0

id
string

The card’s classification unique identifier

Example:
55345ABC34EF
name
string

The card’s classification name

Example:
Students
accounts
Array

The accounts that support the retrieved payment method

Object
id
string

The account’s GUID

number
string

The account’s number

name
string

The account’s name

Examples
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

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

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f21abc565467897543bcdefa12",
    "bank": [
        {
            "sort_code": "20-02-53",
            "account_number": "001002001",
            "bank": "Barclays",
            "branch": "Ascot",
            "iban": "0143240434320434"
        }
    ],
    "payment_method_type": "CARD",
    "payment_gateway_token": "anemail@email.com",
    "card": {
        "brand_name": "AMERICANEXPRESS",
        "card_number": "",
        "last4": "",
        "funding_type": "PREPAID",
        "classification": {
            "id": "55345ABC34EF",
            "name": "Students"
        }
    },
    "accounts": [
        {
            "id": "",
            "number": "",
            "name": ""
        }
    ]
}
Customer Events
Purchase Customer Events
POST /purchases
POST /purchases/{id}/cancel
GET /purchases
POST /purchases/ad_hoc_return
Create Purchase
POST /purchases

Create a new purchase customer event in posted life cycle state

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID nullable

The customer event unique Identifier

Max length: 32
Example:
CEEE83D6E0804A30966F684B0269AD91
contact_id
string GUID required nullable

The contact id that the customer event is created for. Either contact_id or cim must be specified.

Max length: 32
Example:
CEEE83D6E0804A30966F684B0269AD91
cim
string required nullable

The value for a single contact identification medium representing the customer event is created for. Either contact_id or cim must be specified.

Example:
4A30966F684B0269AD91
reference_number
string required

The external system’s reference number that submitted the customer event, the value must be unique and can be used to get or delete a transaction

Example:
RF000001
classification
Object nullable

The classification of the purchase event

id
string GUID required nullable

The classification’s identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
code
string required nullable

The classification’s code

Example:
PCE1234
performed_on
integer epoch

The date that the customer event was performed

Example:
1572423477
currency_code
string

The currency code that the customer event is created against

Example:
EUR
products
Array required

The purchased products for this customer event

Object
family_code
string

ID of Family

Example:
COFFEE
product_sku
string required

The purchased product code

Example:
FREDESPR001
net_amount
number required

The purchased product net amount

Example:
14.15
tax_amount
number required

The purchased product vat amount

Example:
1.04
total_amount
number required

The purchased product total amount (net and vat amount)

Example:
15.19
quantity
integer

The purchased product quantity

Example:
2
spend_request
Object nullable

Information related with the spend request that should be created as part of the purchase customer event

amount
number required nullable

The amount to be spent by the specified spend request in system currency

Example:
2.12
alternative_amount
number required nullable

The amount to be spent by the specified spend request in alternative currency, including points, stickers etc.

Example:
1.75
merchant_tap
Object required

Either tap id or code must be specified

id
string GUID

The business unit tap identifier that the customer event was submitted from.

Example:
CEEE83D6E0804A30966F684B0269AD91
code
string

The business unit tap code that the customer event was submitted from

Example:
EK123456
outlet_tap
Object required

Either tap id or code must be specified

id
string GUID

The business unit tap identifier that the customer event was submitted from.

Example:
CEEE83D6E0804A30966F684B0269AD91
code
string

The business unit tap code that the customer event was submitted from

Example:
CD123456

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The customer event identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 400

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

401 401

The provided API Key or Token is invalid

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /purchases HTTP/1.1 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "contact_id": "CEEE83D6E0804A30966F684B0269AD91",
    "cim": "4A30966F684B0269AD91",
    "reference_number": "RF000001",
    "classification": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "code": "PCE1234"
    },
    "payment_medium_identifier": "42424242",
    "performed_on": 1572423477,
    "currency_code": "EUR",
    "products": [
        {
            "product_sku": "FREDESPR001",
            "net_amount": 14.15,
            "tax_amount": 1.04,
            "total_amount": 15.19,
            "quantity": 2
        }
    ],
    "spend_request": {
        "amount": 2.12,
        "alternative_amount": 1.75
    },
    "merchant_tap": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "code": "EK123456"
    },
    "outlet_tap": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "code": "CD123456"
    }
}
Cancel Purchase
POST /purchases/{id}/cancel

Cancels an existing posted purchase customer event

Path variables

id
string required

The purchase’s GUID

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The customer event identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
POST /purchases/CEEE83D6E0804A30966F684B0269AD91/cancel HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91"
}
List Purchases
GET /purchases

Search for purchases

Request parameters

contact_id
string GUID optional

The contact identifier who performed the purchase

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string optional

The purchase’s reference number

Example:
REF1234
from_date
integer epoch optional

The date from which the purchase was performed.If not specified, then the last 10 purchases will be returned

to_date
integer epoch optional

The date until which the purchase was performed

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

Successful Request

Body
Object
purchases
Array
Object
id
string GUID

The purchase’s GUID

Example:
CEEE83D6E0804A30966F684B0269AD91
number
string

The purchase’s number

Example:
1234
reference_number
string

The purchase’s reference number

Example:
REF1234
life_cycle_state
string

The purchase’s life cycle state

Enumeration:
POSTED
CANCELLED
total_amount
number

The purchase’s total amount

Example:
7
performed_on
integer epoch

The date on which the purchase was performed

Example:
1576486645
performed_by_unit_name
string

The business unit name at which the purchase was performed

Example:
Bravo Coffee
performed_by_unit_id
string GUID

The busienss unit GUID at which the purchase was performed

Example:
CEEE83D6E0804A30966F684B0269AD91
account_id
string GUID

The account agianst which the purchase was submitted

Example:
CEEE83D6E0804A30966F684B0269AD91
classfication_name
string

The purchase event’s classification name

Example:
Card Purchase
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The total number of records overall

Example:
5124
400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1
GET /purchases HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "purchases": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "number": "1234",
            "reference_number": "REF1234",
            "life_cycle_state": "POSTED",
            "total_amount": 7,
            "performed_on": 1576486645,
            "performed_by_unit_name": "Bravo Coffee",
            "performed_by_unit_id": "CEEE83D6E0804A30966F684B0269AD91",
            "account_id": "CEEE83D6E0804A30966F684B0269AD91",
            "classfication_name": "Card Purchase"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Ad Hoc Return of Goods
POST /purchases/ad_hoc_return

Ad hoc return of physical goods

Request headers

api_key
string optional

The secret api key for API calls to ensure that the client is trusted

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
contact_id
string GUID required nullable

The contact id that the customer event is created for (either contact_id or cim must be specified)

Max length: 32
Example:
CEEE83D6E0804A30966F684B0269AD91
cim
string required nullable

The value for a single contact identification medium representing the customer event is created for (either contact_id or cim must be specified)

Example:
4A30966F684B0269AD91
amount
number required

The purchased amount of goods that are returned

Example:
123.45
currency_code
string nullable

The currency code

Example:
EUR
merchant_tap
Object required nullable

Information about the merchant transaction acquiring point

id
string GUID required nullable

The business unit tap identifier that the customer event was submitted from (either id or code must be specified)

Example:
CEEE83D6E0804A30966F684B0269AD91
code
string required nullable

The business unit tap code that the customer event was submitted from (either id or code must be specified)

Example:
EK123456
outlet_tap
Object required nullable

Information about the outlet transaction acquiring point

id
string GUID required nullable

The business unit tap identifier that the customer event was submitted from (either id or code must be specified)

Example:
CEEE83D6E0804A30966F684B0269AD91