BackOffice Admin

https://sandbox.crm.com/backoffice/v1
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 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.

Change Log

Release Date 14th Sept 2020

This is the first release of the CRM V5 platform API’s

API Documentation
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.

API Reference

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.

Authentication

CRM.COM Back-Office API uses either API Keys to authenticate requests or an authentication JWT token obtained from a user successful logging in.

SECURITY NOTICE

All API requests must be made over HTTPS. Any request made over plain HTTP or without authentication will fail. In addition, 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 or client-side code.

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" 
Requests

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.
Responses

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"
        ]
    }
Response Codes

Below is a list of our common HTTP response codes that can be returned.

200 OK

The request has succeeded

400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Operations
Accounts

What s an account

POST /contacts/{id}/accounts
PUT /accounts/{id}
GET /contacts/{id}/accounts
POST /accounts/{id}/life_cycle_state
GET /journals
GET /accounts/{id}/statement
Add Account for Contact
POST /contacts/{id}/accounts

Add a new customer account to an existing contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification_id
string GUID nullable

The account’s classification ID

Example:
4AD9C84FA60F9FE407140E20F707726A
currency_code
string nullable

The account’s currency

Example:
EUR
is_primary
boolean nullable

If set to true, then the account will be set as the primary one even if a different one exists

Example:
true
billing_address_id
string GUID nullable

The unique identification of a contact address which will be set as the billing address of the account. By default, the primary addres (if it exists) will be provided

Example:
E407140E20F707726A4AD9C84FA60F9F

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1 

Content-Type: application/json

{
    "classification_id": "4AD9C84FA60F9FE407140E20F707726A",
    "currency_code": "EUR",
    "is_primary": true,
    "billing_address_id": "E407140E20F707726A4AD9C84FA60F9F"
}
Update Account
PUT /accounts/{id}

Update the account of a contact

Path variables

id
string GUID required

The account identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification_id
string GUID

The account’s classification ID

Example:
4AD9C84FA60F9FE407140E20F707726A
is_primary
boolean

If set to true, then the account will be set as the primary one even if a different one exists

Example:
true
billing_address_id
string GUID

The unique identification of a contact address which will be set as the billing address of the account. By default, the primary addres (if exists) will be provided

Example:
4AD9C84FA60F9FE407140E20F707726A
credit_limit
number

Sets the credit limit of the account, within the allowed range based on settings

Example:
200

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
PUT https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "classification_id": "4AD9C84FA60F9FE407140E20F707726A",
    "is_primary": true,
    "billing_address_id": "4AD9C84FA60F9FE407140E20F707726A",
    "credit_limit": 200
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Contact Accounts
GET /contacts/{id}/accounts

Get a list of Contact Accounts. Normally a contact will have a single account but multiple accounts can be used to service different currencies, or different spending profiles.

Path variables

id
string GUID required

The contact identifier whose accounts will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

is_primary
boolean optional

If set to true, then only the primary account of the contact will get retrieved

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
is_primary
boolean

Indicates if this is the primary account of the contact

Example:
true
name
string

The account name

Example:
Default
number
string

The Account number

Example:
AC123456
life_cycle _state
string

The account’s life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
currency_code
string

The account’s currency

Example:
EUR
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
balance
number

The account’s calculated balance

Example:
200
credit_limit
number

The account’s credit limit

Example:
100
overdue_amount
number

The unpaid amount that is passed its due date

Example:
50
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "is_primary": true,
            "name": "Default",
            "number": "AC123456",
            "life_cycle _state": "TERMINATED",
            "currency_code": "EUR",
            "classification": {
                "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                "name": "Delivery Purchase"
            },
            "balance": 200,
            "credit_limit": 100,
            "overdue_amount": 50
        }
    ]
}
Update Account's Life Cycle State
POST /accounts/{id}/life_cycle_state

Change the life cycle state of the Account

Path variables

id
string GUID required

The account identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string required

The life cycle state that the account will changed into

Enumeration:
SUSPENDED
ACTIVE
TERMINATED
Example:
SUSPENDED
transfer_to_account_id
string GUID nullable

The account to which any account balance will get transfered, in case of Termination. Required when terminating the account

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the account

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
POST https://sandbox.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/life_cycle_state HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "SUSPENDED",
    "transfer_to_account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Journals
GET /journals

Retrieve all account and wallet journal entries for all contacts, or based on request parameters

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_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
entity
string optional

Which journals should be retrieved, blank = both Account & Wallet

Enumeration:
ACCOUNT
WALLET
type
string optional

Type of journal entry action, if not specified then all journals are retrieved

Enumeration:
DEBIT
CREDIT
transaction_type
string optional

Type of financial transaction

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
PAYMENT_CANCELLATION
REFUND
PAYOUT
TOPUP
TRANSFER
PASS_REDEMPTION
AD_HOC_RETURN
SPEND
AWARD
PURCHSE_CANCELLATION
BACKEND_SPEND
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
posted_date
integer epoch optional

Journal entries posted on this date

reference_number
string optional

The reference number of the journal’s related financial or wallet entity

Example:
A09967
amount
number optional

Journal entry amount

Example:
101.55
contact_id
string optional

Unique Contact id for which to retrieve journal entries

Example:
5a4461f7-9479-4249-8687-eb1661be56d7
account_id
string optional

Unique account id to get journal entries

Example:
0d4d2028-caa6-4a06-9c91-aaa0a195838c
wallet_id
string optional

Unique wallet id to get journal entries

Example:
77832a67-51b2-4a4b-8ee4-dc9bd07dbe59
organisation_id
string optional

Organisation id to get journal entries

Example:
238c3a13-f47a-4712-9217-afce60b4615a

Responses

200 OK
Body
Object
content
Array
Object
id
string

Journal id

Example:
2f4ea11b-12a6-4321-92d1-f4ede511e203
entity
string

Journal entity type

Enumeration:
ACCOUNT
WALLET
type
string

Type of journal entry action

Enumeration:
DEBIT
CREDIT
Example:
CREDIT
posted_date
integer epoch

Journal posted date

Example:
2343342445
account
Object

Contact’s account details

id
string

Unique id of account for which the jounral entry was posted

Example:
MP09E31269B76D7A65ACCE45B2E68DFD
number
string

Unique account number

Example:
964AC123456
wallet
Object

Contact’s wallet details

id
string GUID

Unique wallet id

Example:
DN89331269B76D7A65ACCE45B2E68DFD
code
string

Unique wallet code

Example:
W00123456
entity_id
string GUID

The unique identifier of the journal entity (e.g. invoice_id, top-up_id, transfer_id etc.)

Example:
6bf75c2b-e9d1-43bc-b5db-a7555919bf04
transaction_type
string

The type of the event

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
PAYMENT_CANCELLATION
REFUND
PAYOUT
TOPUP
TRANSFER
PASS_REDEMPTION
AD_HOC_RETURN
SPEND
AWARD
PURCHSE_CANCELLATION
BACKEND_SPEND
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
entity_number
string

Entity number, e.g. invoice number, credit note number, refund number

Example:
CN88942
reference_number
string

Can be: a) Reference number - if the transaction is of type payment, invoice, credit note, payment cancellation, refund. OR b) Code - if the transaction is a top-up or a transfer

Example:
A09967
initial_type
string

The initiating type of an AWARD transaction

Enumeration:
PURCHASE

Award is a result of a purchase event

ACHIEVEMENT

Award is a result of a reward achievement offer

contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
amount
number

Transaction amount

Example:
9.99
currency
string

Transaction currency code

Example:
EUR
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/journals HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id": "2f4ea11b-12a6-4321-92d1-f4ede511e203",
            "entity": "WALLET",
            "type": "CREDIT",
            "posted_date": 2343342445,
            "account": {
                "id": "MP09E31269B76D7A65ACCE45B2E68DFD",
                "number": "964AC123456"
            },
            "wallet": {
                "id": "DN89331269B76D7A65ACCE45B2E68DFD",
                "code": "W00123456"
            },
            "entity_id": "6bf75c2b-e9d1-43bc-b5db-a7555919bf04",
            "transaction_type": "SPEND",
            "entity_number": "CN88942",
            "reference_number": "A09967",
            "initial_type": "ACHIEVEMENT",
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "amount": 9.99,
            "currency": "EUR"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Account Statement
GET /accounts/{id}/statement

Retrieves the account & wallet transactions for a specific Contact account

Path variables

id
string GUID required

The account identifier to retrieve transactions for

Example:
76D7A65ACCE45B2E68DFDCAD1E31269B

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC
from_date
integer epoch required

Start date of statement period

to_date
integer epoch required

End date of statement period

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
statement
Object
type
string

Transactions affecting either the account or open/commerce wallet

Enumeration:
ACCOUNT

Account transactions

WALLET_OPEN

Wallet open transactions

WALLET_COMMERCE

Wallet commerce transactions

number
string

Account or Wallet number

Example:
W3900853
opening_balance
number

Balance of account/wallet brought forward from previous period

Example:
200
balance
number

Final balance

Example:
347.5
lines
Array

Statement lines

Object
date
string epoch

Transaction date

Example:
2343342445
type
string

Type of financial transaction

Enumeration:
DEBIT
CREDIT
Example:
CREDIT
amount
number

Transaction amount

Example:
3.5
activity
string
Enumeration:
SETTLEMENT_PROCESS
PAYMENT
INVOICE
CREDIT_NOTE
PAYMENT_CANCELLATION
REFUND
TOP_UP
TRANSFER
PASS_REDEMPTON
AD_HOC_RETURN
SPEND
AWARD
PURCHASE_CANCELLATION
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
activity_number
string

The reference number of the transaction (if available), e.g. reference number of a payment or a transfer

Example:
TRF08992
details
string

Transaction details

Example:
Sally's Flower Shop
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "is_primary": true,
            "name": "Default",
            "number": "AC123456",
            "life_cycle _state": "ACTIVE",
            "currency_code": "EUR",
            "classification": {
                "id": "E31269CAD1B76D7A65ACCE45B2E68DFD",
                "name": "VIP"
            },
            "balance": 200,
            "credit_limit": 100,
            "overdue_amount": 50,
            "billing_address_id": "7A65ACCCAD1E31269B76DE45B2E68DFD",
            "wallet": {
                "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                "code": "W3900853",
                "balance": 200.2,
                "currency_code": "EUR",
                "life_cycle_state": "TERMINATED"
            }
        }
    ]
}
Account Financials
GET /accounts/{id}/financials
Get Account Financials
GET /accounts/{id}/financials

Get a single Account with its financial information

Path variables

id
string GUID required

The unique identification of the Account to be retrieved.

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
name
string

The account’s name

Example:
John Smith AC00123456
number
string

The account’s number

Example:
AC00123456
is_primary
boolean

Defines whether the account is the primary one of the contact

Example:
true
life_cycle_state
string

The account’s life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
currency_code
string

The account’s currency (3 code currency)

Example:
EUR
balance
number

The account’s calculated balance

Example:
200
overdue_amount
number

The unpaid amount that is passed its due date

Example:
100.5
credit_limit
number

The account’s credit limit

Example:
98
opening_balance
number

The opening balance brought forwards after the latest closed accounting period

Example:
100.5
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
accounting_period
Object

The latest accounting period for which the account’s opening balance was calculated

id
string

The ID of the latest closed accounting period

name
string

The name of the account’s latest accounting period

Example:
OCTOBER2018
billing_address
Object
id
string GUID

The id of the billing address

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_line_1
string
Example:
2265 Oak Street
address_line_2
string
state_province_county
string
Example:
New York
town_city
string
Example:
Old Forge
postal_code
string
Example:
13420
country_code
string
Example:
USA
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
GET https://sandbox.crm.com/backoffice/v1/accounts/4AD9C84FA60F9FE407140E20F707726A/financials HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "John Smith AC00123456",
    "number": "AC00123456",
    "is_primary": "true",
    "life_cycle_state": "SUSPENDED",
    "currency_code": "EUR",
    "balance": 200,
    "overdue_amount": 100.5,
    "credit_limit": 98,
    "opening_balance": 100.5,
    "classification": {
        "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
        "name": "Delivery Purchase"
    },
    "accounting_period": {
        "id": "",
        "name": "OCTOBER2018"
    },
    "billing_address": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "address_line_1": "2265 Oak Street",
        "address_line_2": "",
        "state_province_county": "New York",
        "town_city": "Old Forge",
        "postal_code": "13420",
        "country_code": "USA"
    }
}
Account Rewards
PUT /accounts/{id}/rewards
GET /accounts/{id}/rewards
POST /accounts/{id}/reward_schemes
DELETE /accounts/{id}/reward_schemes/{reward_scheme_id}
POST /accounts/{id}/merchants
DELETE /accounts/{id}/merchants/{merchant_id}
Update Account Rewards
PUT /accounts/{id}/rewards

Update the reward attributes of the primary account of a contact

Path variables

id
string GUID required

The account (identifier) whose reward attributes will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

Only Primary Accounts of a Contact hold Reward information

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
signed_up_on
integer epoch nullable

The date that the customer first signed up

Example:
1583846865
signed_up_organisation_id
string GUID nullable

The organisation identifier that signed up the customer (first time)

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
spending_blocked_status
boolean nullable

Defines whether the spending is blocked for the specific account

Example:
true
automatic_spend_settings
Object nullable

Information about the automatic spend settings for the account

enable_automatic_spend
boolean required

Defines whether automatic spend is enabled for the account

Example:
false
automatic_spend_preference
string nullable

Defines whether automatic spends will occur on the next purchase of a specific merchant or based on wallet balance and purchase amount to a group of merchants

Enumeration:
NEXT_MERCHANT_PURCHASE
ALL_MERCHANT_PURCHASE
minimum_wallet_balance
number nullable

The minimum wallet balance amount that should be available for the spend to be performed. Applicable when automatic spend preference is for all merchant purchases

from_purchase_amount
number nullable

The min amount (inclusive) that the purchase customer event total amount should be in order for the automatic spend to be applied. Applicable when automatic spend preference is for all merchant purchases

Example:
1.76

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
PUT https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/rewards HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "signed_up_on": 1583846865,
    "signed_up_organisation_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "spending_blocked_status": "true",
    "automatic_spend_settings": {
        "enable_automatic_spend": "false",
        "automatic_spend_preference": "ALL_MERCHANT_PURCHASE",
        "minimum_wallet_balance": 1,
        "from_purchase_amount": 1.76
    },
    "preferred_payment_method_id": "CAD1E31269B76D7A65ACCE45B2E68DCD"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Get Account Rewards
GET /accounts/{id}/rewards

Get a single account, along with its reward details

Path variables

id
string GUID required

The account (identifier) which reward details will be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Notes

Only Primary Accounts of a Contact hold Reward information

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The account’s name

Example:
John Smith AC00123456
number
string

The account’s number

Example:
AC00123456
currency_code
string

The account’s currency (3 code currency)

Example:
EUR
sign_up_on
integer epoch

The date when the account was signed up for the first time

Example:
1583846865
sign_up_organisation
Object

Information about the organisation that sign up the account for the first time

id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
CRMdotCOM
spending_blocked_status
boolean

Defines whether the account can spend or not

Example:
false
spending_blocked_date
integer epoch

The date that the spending status of the account was updated

Example:
1583846865
spending_blocked_user
Object

Information about the user that updated the spending status of the account

id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
email_address
string

The user’s email address

Example:
johndoe@crm.com
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
automatic_spend_settings
Object

Information about the automatic spend settings for the account

enable_automatic_spend
boolean

Defines whether automatic spend is enabled for the account

Example:
true
automatic_spend_preference
string

Defines whether automatic spends will occur on the next purchase of a specific merchant or based on wallet balance and purchase amount to a group of merchants

Enumeration:
NEXT_MERCHANT_PURCHASE
ALL_MERCHANT_PURCHASE
minimum_wallet_balance
number

The minimum wallet balance amount that should be available for the spend to be performed. Applicable when automatic spend preference is for all merchant purchases

Example:
0.52
from_purchase_amount
number

The min amount (inclusive) that the purchase customer event total amount should be in order for the automatic spend to be applied. Applicable when automatic spend preference is for all merchant purchases

Example:
1.78
merchants
Array

Information about the merchants that automatic spending is allowed (Deprecated, replaced by Organisations)

Object
id
string GUID

The merchant record identifier

Example:
REC1E31269B76D7A65ACCE45B2E68DFD
is_next_visit
boolean

Defines whether the merchant is setup for automatic spend on the next visit

Example:
false
organisation
Object

Information about organisation

id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Bravo Coffee
organisations
Array

Organisation Automatic Spend Preferences

Object
id
string GUID

The record identifier

Example:
REC1E31269B76D7A65ACCE45B2E68DFD
is_next_visit
boolean

Defines whether the merchant is setup for automatic spend on the next visit

Example:
false
organisation
Object

Organisation information

id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Bravo Coffee
reward_tier
Object

Information about the account’s reward tier

id
string GUID

The reward tier identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward tier name

Example:
Gold
color
string

The designated hexadecimal code of the tier’s color

Example:
#d4af37
period_value_units
number

The account’s value units that accumulated during the last rolling period

Example:
222
lifetime_value_units
number

The account’s value units that accumulated overall

Example:
333
tier_progression
Array

Details about The progression percentage for each reward tier

Object
percentage
number

The progression percentage until the reward tier

Example:
45.98
tier
Object

Details about the reward tier

id
string GUID

The reward tier identifier

Example:
41ed2390-4058-81a2-d41b-18acaea22c84
name
string

The reward tier name

Example:
Gold
value_units
integer

The tier (threshold) value units (inclusive)

Example:
2500
remaining_value_units
integer

The remaining value units to reach this tier

Example:
123
joined_reward_schemes
Array

Information about the reward schemes that the account has signed up to

Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward scheme name

Example:
CRMdotCOM Scheme
signed_up_on
integer epoch

The date when the account was signed up on the specific reward scheme

Example:
1583846865
email_address
string

The email address that was used during sign up (applicable if the reward scheme is a close loop scheme based on email domains)

Example:
johndoe@crm.com
sign_up_option
string

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP
SELF_SIGN_UP
CLOSE_LOOP_SIGN_UP
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
GET https://sandbox.crm.com/backoffice/v1/accounts/41dc3d8a-5ab2-3dc8-83d5-33501eb1949f/rewards HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "name": "John Smith AC00123456",
    "number": "AC00123456",
    "currency_code": "EUR",
    "reward_tier": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "Gold",
        "color": "#d4af37",
        "period_value_units": 222,
        "lifetime_value_units": 333,
        "next_tier_progression": 45.98
    }
}
Sign up to a Reward Scheme
POST /accounts/{id}/reward_schemes

Sign up the account to a specific reward scheme

Path variables

id
string GUID required

The account (identifier) that will be signed up to the reward scheme

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
reward_scheme_id
string GUID required

The reward scheme that the account has signed up

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
email_address
string nullable

The email address of the customer requestng to sign uo to a reward scheme based on supported domains

Example:
johndoe@crm.com
sign_up_code
string nullable

The code that will verify that the customer is allowed to sign up to a close loop reward scheme

Example:
ABCDEFG1234
sign_up_date
integer epoch nullable

The date that the account has signed up (if not specified, defaults to current date)

Example:
1589796854

Responses

200 200

OK

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DXD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
POST https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/reward_schemes HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "reward_scheme_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "email_address": "johndoe@crm.com",
    "sign_up_code": "ABCDEFG1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DXD"
}
Sign out from a Reward Scheme
DELETE /accounts/{id}/reward_schemes/{reward_scheme_id}

Sign out the account from a specific reward scheme

Path variables

id
string GUID required

The account (identifier) that will be signed off from the reward scheme

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
reward_scheme_id
string GUID required

The reward scheme (identifier) that the account has signed off

Example:
CAD1E31269B76D7A65ACCE45B2E68DXD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DXD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Add Merchants
POST /accounts/{id}/merchants

Add a set of new merchants for automatic spends for that account

Path variables

id
string GUID required

The account (identifier) whose merchant preferencees will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
merchants
Array required

Defines a list of merchants that are authorised to perform automatic awards spending for that account

Unique items: YES
Object
organisation_id
string GUID required

The organisation identifier that should be authorised to perform automatic awards spending

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
is_next_visit
boolean nullable

Defines whether the merchant is setup for automatic spend on the next visit

Example:
false

Responses

200 200

OK

Body
Object
merchants
Array

A list of merchants that are authorised to perform automatic awards spending for that account

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
POST https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/merchants HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "merchants": [
        {
            "organisation_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "is_next_visit": "false"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "merchants": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
        }
    ]
}
Remove Merchant
DELETE /accounts/{id}/merchants/{merchant_id}

Remove an exisintg merchant from an account’s automatic spend preferences

Path variables

id
string GUID required

The account (identifier) whose reward attributes will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
merchant_id
string GUID required

The merchant (identifier) that will be removed from the spend preferences

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

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

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

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

404 Not Found

The requested resource does not exist

500 Internal Server Error

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

502 Bad Gateway

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

503 Service Unavailable

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

504 Gateway Timeout

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

Example 1
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/merchants/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Wallets
POST /wallets
PUT /wallets/{id}
GET /wallets/{id}
GET /wallets
GET /wallets/{id}/balances
POST /journals
Create Wallet
POST /wallets

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string required

The contact that owns the Wallet

Example:
3fc0809f-ed91-4b68-b912-5bd6064d019b
code
string

The Wallet’s code. If not specified, then a unique and random 16-digit code is assigned to the Wallet.

Example:
994434532330012
currency_code
string

The wallet’s primary currency. If not specified, then the base currency of the Cloud operator is used

Example:
EUR
limit_rules
Array
Object
name
string
Example:
VIP
maximum_amount
number
Example:
9.99
maximum_number
integer
Example:
10
period
string
Example:
ANNUAL
transaction_type
Array
Example:
["TOPUP"]
string
Example:
TOPUP
Update Wallet
PUT /wallets/{id}

Updates a single Wallet.

Path variables

id
string required

The unique identifier of the Wallet to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

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

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
auto_topup
Object
threshold
number
Example:
0.01
amount
number
Example:
10.5
payment_method
string
Example:
CARD
payment_method_id
string
termed_topup
Object
amount
number
Example:
10.5
frequency
Object
period
string
Example:
MONTHS
value
integer