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
billing_address_id
string GUID

The billing address of the account which is the same as one of the contact’s addresses

Example:
7A65ACCCAD1E31269B76DE45B2E68DFD
wallet
Object

The account’s wallet information (if available)

id
string GUID

The wallet identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
code
string

Wallet code

Example:
W3900853
balance
number

Wallet balance

Example:
200.2
currency_code
string

Wallet’s currency

Example:
EUR
life_cycle_state
string

The wallet’s life cycle state

Enumeration:
EFFECTIVE
TERMINATED
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"
            }
        }
    ]
}
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
transfer_to_account_id
string GUID nullable

The account to which any account/wallet balance will get transfered, in case of Termination

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 /accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/life_cycle_state HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "TERMINATED",
    "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
accounting_period_id
string GUID

The ID of the latest closed accounting period

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
accounting_period_name
string

The name of the account’s latest accounting period

Example:
OCTOBER2018
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
wallet
Array

The account’s wallet information (if available)

Object
id
string GUID

The wallet’s unique identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

A unique 16-digit code that if not provided, it is auto-generated

Example:
W00123456
balance
number

The total balance of the wallet

Example:
150.5
commerce_balance
number

The commerce balance of the wallet

Example:
98
open_balance
number

The open balance of the wallet

life_cycle_state
string

The wallet’s life cycle state

Enumeration:
EFFECTIVE
TERMINATED
minimum_balance
number

The minimum wallet balance threshold. If not provided, the global rules apply

Example:
9
limit_rules
Array

Defines the limit rules applied on specific wallet. If not provided, the global rules apply

Object
minimum_amount
number

The minimum amount allowed

Example:
100.5
maximum_amount
number

The maximum amount allowed

Example:
200
period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL
transaction_type
string

The wallet transaction type for which the limit is applied

Enumeration:
CREDIT
DEBIT
TOPUP
TRANSFER
auto_topup
Object
threshold
number

Sets the threshold for the auto topup to be performed

Example:
10.5
amount
number

The amount to get topped up

Example:
10.5
payment_method
string

Indicates the method of collecting money

Enumeration:
CASH
BANK_TRANSFER
CARD
DIRECT_DEBIT
WALLET
PAYPAL
ACCOUNT
payment_method_id
string

The contact’s actual preferred payment method. Required and mandatory only for online payments (Card, Wallet, PayPal and Account). Defaults to the primary payment method, if any.

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/41dc3d8a-5ab2-3dc8-83d5-33501eb1949f/financials HTTP/1.1 

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "John Smith AC00123456",
    "number": "AC00123456",
    "wallet": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "code": "W00123456",
            "balance": 150.5,
            "commerce_balance": 98,
            "open_balance": 1,
            "life_cycle_state": "EFFECTIVE"
        }
    ]
}
Account Wallets
POST /accounts/{id}/wallets
PUT /wallets/{id}
POST /wallets/{id}/actions
GET /wallets/{id}/balances
POST /journals
Add Wallet for Account
POST /accounts/{id}/wallets

Add a new wallet for an existing 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
minimum_balance
number

The minimum wallet balance threshold. If not provided, the global rules apply

Example:
10
limit_rules
Array

Defines the limit rules applied on specific wallet. If not provided, the global rules apply

Object
limit_amount
number

The maximum amount allowed

Example:
100
transaction_type
string

The wallet transaction type for which the limit is applied

Enumeration:
CREDIT
DEBIT
period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL

Responses

200 200

OK

Body
Object
id
string GUID

The wallet identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
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/wallets HTTP/1.1 

Content-Type: application/json

{
    "minimum_balance": 10,
    "limit_rules": [
        {
            "limit_amount": 100,
            "transaction_type": "DEBIT",
            "period": "DAILY"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Wallet
PUT /wallets/{id}

Update the wallet of an account

Path variables

id
string GUID required

The wallet 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
minimum_balance
number

The minimum wallet balance threshold. If not provided, the global rules apply

Example:
10
limit_rules
Array

Defines the limit rules applied on specific wallet. If not provided, the global rules apply

Object
minimum_amount
number

The minimum amount allowed

Example:
100
maximum_amount
number

The maximum amount allowed

Example:
200
period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL
transaction_type
string

The wallet transaction type for which the limit is applied

Enumeration:
CREDIT
DEBIT
TOPUP
TRANSFER
auto_topup
Object
threshold
number

Sets the threshold for the auto topup to be performed

Example:
10.5
amount
number

The amount to get topped up

Example:
10.5
payment_method
string

Indicates the method of collecting money

Enumeration:
CASH
ACCOUNT_DEBIT
CARD
WALLET
payment_method_id
string

The contact’s actual preferred payment method. Required and mandatory only for online payments (Card, Wallet and Account Debit). Defaults to the primary payment method, if any.

Responses

200 200

OK

Body
Object
id
string GUID

The wallet 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://stagingapi.crm.com/backoffice/v1/wallets/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "minimum_balance": 10,
    "limit_rules": [
        {
            "minimum_amount": 100,
            "maximum_amount": 200,
            "period": "DAILY",
            "transaction_type": "TRANSFER"
        }
    ],
    "auto_topup": {
        "threshold": 10.5,
        "amount": 10.5,
        "payment_method": "ACCOUNT",
        "payment_method_id": ""
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Actions on Wallet
POST /wallets/{id}/actions

Change the life cycle state of the Wallet

Path variables

id
string GUID required

The wallet identifier that will be updated

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8

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
action
string

Defines the life cycle state of the wallet. If selected, then all of the above will not be taken into consideration

Enumeration:
TERMINATED
EFFECTIVE

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the wallet

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
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://stagingapi.crm.com/backoffice/v1/wallets/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "EFFECTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Wallet Balances
GET /wallets/{id}/balances

Get the wallet’s balances split per spend condition

Path variables

id
string GUID required

The unique identification of the wallet whose balance spend conditions will be retrieved.

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8

Request parameters

spend_condition_id
string GUID optional

The id of a specific spend condition (optional). If not provided then all spend conditions are retrieved

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
include_expiration
boolean optional

If set to true, then the expiration information will also be retrieved

Example:
true
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

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
Array
Object
id
string GUID

The spend condition group identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
name
string

The name of the spend condition group

Example:
Happy Hour
amount
number

The amount that is allocated to the specified spend condition

Example:
100.5
organisations
Array

The organisations where the amount can be spent at

Object
id
string GUID

The organsiation identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
name
string

The name of the organisation

Example:
Cafe
locations
Array

The location of the organisation

Object

Information about the organisation’s location

name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
products
Array

The products that the amount can be spent for

Object
id_type
string

The type of the ID to be provided

Enumeration:
PRODUCT
FAMILY
TYPE
BRAND
CATEGORY
id
string GUID

The ID of the product (based on the type provided)

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
name
string

The name of the product

Example:
Coffee
description
string

The descrtipion of the product

Example:
Brazilian Coffee
timings
Array

The time when the amount can be spent

Object
month
integer

The month as a condition (1-12)

Example:
1
day
integer

The day of the week as condition (1-7), 1 is Sunday

Example:
1
start_time
string

The start time of the day in 24 Hour format

Example:
19:00
end_time
string

The end time of the day in 24 Hour format

Example:
21:00
expiration
Object

Defines the amounts expiring in periods. Available only if the parameter include_expiration is set to true

zero_to_thirty
number

The amount that will expire in up to 30 days

Example:
50.5
thirty_to_sixty
number

The amount that will expire from 30 to 60 days

Example:
50.5
sixty_to_ninety
number

The amount that will expire from 60 to 90 days

Example:
50.5
ninety_plus
number

The amount that will expire in more than 90 days

Example:
50.5
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://stagingapi.crm.com/backoffice/v1/wallets/4AD9C84FA60F9FE407140E20F707726A/balances HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "amount": 100.5,
        "id": "4AD9C84FA60F9FE407140E20F707726A",
        "name": "Happy Hour",
        "organisations": [
            {
                "id": "4AD9C84FA60F9FE407140E20F707726A",
                "name": "Cafe",
                "locations": [
                    {
                        "name": "Head Office",
                        "address_line_1": "Elia Papakyriakou 21",
                        "address_line_2": "7 Tower Stars",
                        "state_province_county": "Egkomi",
                        "town_city": "Nicosia",
                        "postal_code": "2415",
                        "country_code": "CY",
                        "lat": "35.157115",
                        "lon": "33.313719",
                        "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                    }
                ]
            }
        ],
        "products": [
            {
                "id_type": "FAMILY",
                "id": "4AD9C84FA60F9FE407140E20F707726A",
                "name": "Coffee",
                "description": "Brazilian Coffee"
            }
        ],
        "timings": [
            {
                "month": 1,
                "day": 1,
                "start_time": "19:00",
                "end_time": "21:00"
            }
        ],
        "expiration": {
            "zero_to_thirty": 50.5,
            "thirty_to_sixty": 50.5,
            "sixty_to_ninety": 50.5,
            "ninety_plus": 50.5
        }
    }
]
Create Wallet Journal
POST /journals

Create a wallet debit or credit journal entry

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
wallet_id
string GUID

The unique identifier for which the journal entry will be created

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
amount
number

The amount of the journal

Example:
10
type
string

The type of the journal

Enumeration:
CREDIT
DEBIT
description
string

The description of the journal

Example:
Credit adjustment by 10 EUR
spend_condition_id
string GUID

The unique identifier of the related spend condition

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
valid_from
integer epoch

The valid from date

Example:
1587988965
valid_to
integer epoch

The valid to date

Example:
1587988965
created_on
integer epoch

The date and time when the journal actually created

Example:
1588081851
allow_below_zero
boolean

Allows a wallet debit journal to take the wallet balance below zero. By default, the wallet balance cannot go below zero.

Example:
true

Responses

200 200

OK

Body
Object
id
string GUID

The wallet journal identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
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