BackOffice Admin
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.
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.
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.
CRM.COM Back-Office API uses either API Keys to authenticate requests or an authentication JWT token obtained from a user successful logging in.
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"
API requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.
| Method | Usage |
|---|---|
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object to the targeted endpoint. |
| PUT | To update the information on an existing object, the PUT method should be used. This will update the specified object if it is found using the provided values, regardless of their current values. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource’s availability prior to issuing an update command, the final state will be the same regardless of its existence. Requests using the PUT method do not need to check the current attributes of the object. |
| DELETE | To remove an existing object from your environment, the DELETE method should be used. Similar to PUT method, the DELETE method is idempotent. |
| GET | For retrieving information about customers, purchases or orders, the GET method should be used. Any requested information will be returned as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the retrieved objects. |
Along with the HTTP methods that the API responds to, CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request.
In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.
| HTTP Status | Description |
|---|---|
| 2XX | Return codes in the 200 range indicate that the request was fulfilled successfully and that no error was encountered. |
| 4XX | Return codes in the 400 range, typically, indicate that there was an issue with the request that was sent. Most common reasons could be an invalid authentication method, unauthorised requests or the object that you are requesting does not exist. |
| 5XX | Return codes in the 500 range indicate that there is a server-side problem and CRM.COM cannot fulfill your request at the moment. |
Most of our 4XX range errors that could be handled programmatically contain all the necessary details for a better integration handling. Such details are
- HTTP Status Code & Error are used for programmatic consumption
- Message is human-readable and can be used as a default error message
- Parameters are used for programmatic consumption and can be used for enhancing the interface error message with additional information
4XX ERROR RESPONSE EXAMPLE
An example of a customer not found error is as follows
HTTP/1.1 400 Bad Request
{
"status": 400,
"message": "Record not found.",
"error": "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION",
"parameters": [
"contact",
"789dacae-cf71-414f-9483-ca88acaa46432"
]
}
The request has succeeded
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
What s an account
{id}/accounts{id}{id}/accounts{id}/life_cycle_state{id}/statement{id}/accountsAdd a new customer account to an existing contact
Path variables
The contact identifier that will be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The account’s classification ID
The account’s currency
If set to true, then the account will be set as the primary one even if a different one exists
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
Responses
OK
Body
The account identifier
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"
}{id}Update the account of a contact
Path variables
The account identifier that will be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The account’s classification ID
If set to true, then the account will be set as the primary one even if a different one exists
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
Sets the credit limit of the account, within the allowed range based on settings
Responses
OK
Body
The account identifier
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"
}{id}/accountsGet 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
The contact identifier whose accounts will be retrieved
Request parameters
If set to true, then only the primary account of the contact will get retrieved
Defines on which attribute the results should be sorted
The page number that should be retrieved
The size (total records) of each page
Defines how the results will be ordered
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The account identifier
Indicates if this is the primary account of the contact
The account name
The Account number
The account’s life cycle state
The account’s currency
Details about the event classification
The classification identifier
The classification name
The account’s calculated balance
The account’s credit limit
The unpaid amount that is passed its due date
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
}
]
}{id}/life_cycle_stateChange the life cycle state of the Account
Path variables
The account identifier that will be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The life cycle state that the account will changed into
The account to which any account balance will get transfered, in case of Termination. Required when terminating the account
Responses
Successful Request
Body
The unique identifier of the account
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"
}Retrieve all account and wallet journal entries for all contacts, or based on request parameters
Request parameters
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Which journals should be retrieved, blank = both Account & Wallet
Type of journal entry action, if not specified then all journals are retrieved
Type of financial transaction
Journal entries posted on this date
The reference number of the journal’s related financial or wallet entity
Journal entry amount
Unique Contact id for which to retrieve journal entries
Unique account id to get journal entries
Unique wallet id to get journal entries
Organisation id to get journal entries
Responses
Body
Journal id
Journal entity type
Type of journal entry action
Journal posted date
Contact’s account details
Unique id of account for which the jounral entry was posted
Unique account number
Contact’s wallet details
Unique wallet id
Unique wallet code
The unique identifier of the journal entity (e.g. invoice_id, top-up_id, transfer_id etc.)
The type of the event
Entity number, e.g. invoice number, credit note number, refund number
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
The initiating type of an AWARD transaction
Award is a result of a purchase event
Award is a result of a reward achievement offer
Details about the related contact
The contact identifier
The contact full name
The contact unique code
Details about the organisation from where such event was posted
The organisation identifier
The organisation name
Transaction amount
Transaction currency code
The page number
The number of records per page
The overal number of records
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
}
}{id}/statementRetrieves the account & wallet transactions for a specific Contact account
Path variables
The account identifier to retrieve transactions for
Request parameters
Defines on which attribute the results should be sorted
The page number that should be retrieved
The size (total records) of each page
Defines how the results will be ordered
Start date of statement period
End date of statement period
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
Transactions affecting either the account or open/commerce wallet
Account transactions
Wallet open transactions
Wallet commerce transactions
Account or Wallet number
Balance of account/wallet brought forward from previous period
Final balance
Statement lines
Transaction date
Type of financial transaction
Transaction amount
The reference number of the transaction (if available), e.g. reference number of a payment or a transfer
Transaction details
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"
}
}
]
}{id}/financials{id}/financialsGet a single Account with its financial information
Path variables
The unique identification of the Account to be retrieved.
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The account’s name
The account’s number
Defines whether the account is the primary one of the contact
The account’s life cycle state
The account’s currency (3 code currency)
The account’s calculated balance
The unpaid amount that is passed its due date
The account’s credit limit
The opening balance brought forwards after the latest closed accounting period
Details about the event classification
The classification identifier
The classification name
The latest accounting period for which the account’s opening balance was calculated
The ID of the latest closed accounting period
The name of the account’s latest accounting period
The id of the billing address
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"
}
}{id}/rewards{id}/rewards{id}/reward_schemes{id}/reward_schemes/{reward_scheme_id}{id}/merchants{id}/merchants/{merchant_id}{id}/rewardsUpdate the reward attributes of the primary account of a contact
Path variables
The account (identifier) whose reward attributes will be updated
Notes
Only Primary Accounts of a Contact hold Reward information
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The date that the customer first signed up
The organisation identifier that signed up the customer (first time)
Defines whether the spending is blocked for the specific account
Information about the automatic spend settings for the account
Defines whether automatic spend is enabled for the account
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
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
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
Responses
OK
Body
The account identifier
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"
}{id}/rewardsGet a single account, along with its reward details
Path variables
The account (identifier) which reward details will be retrieved
Notes
Only Primary Accounts of a Contact hold Reward information
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The account identifier
The account’s name
The account’s number
The account’s currency (3 code currency)
The date when the account was signed up for the first time
Information about the organisation that sign up the account for the first time
The organisation identifier
The organisation name
Defines whether the account can spend or not
The date that the spending status of the account was updated
Information about the user that updated the spending status of the account
The user identifier
The user’s email address
The user’s first name
The user’s last name
Information about the automatic spend settings for the account
Defines whether automatic spend is enabled for the account
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
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
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
Information about the merchants that automatic spending is allowed (Deprecated, replaced by Organisations)
The merchant record identifier
Defines whether the merchant is setup for automatic spend on the next visit
Information about organisation
The organisation identifier
The organisation name
Organisation Automatic Spend Preferences
The record identifier
Defines whether the merchant is setup for automatic spend on the next visit
Organisation information
The organisation identifier
The organisation name
Information about the account’s reward tier
The reward tier identifier
The reward tier name
The designated hexadecimal code of the tier’s color
The account’s value units that accumulated during the last rolling period
The account’s value units that accumulated overall
Details about The progression percentage for each reward tier
The progression percentage until the reward tier
Details about the reward tier
The reward tier identifier
The reward tier name
The tier (threshold) value units (inclusive)
The remaining value units to reach this tier
Information about the reward schemes that the account has signed up to
The reward scheme identifier
The reward scheme name
The date when the account was signed up on the specific reward scheme
The email address that was used during sign up (applicable if the reward scheme is a close loop scheme based on email domains)
Defines how customers can sign up to the reward scheme
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
}
}{id}/reward_schemesSign up the account to a specific reward scheme
Path variables
The account (identifier) that will be signed up to the reward scheme
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The reward scheme that the account has signed up
The email address of the customer requestng to sign uo to a reward scheme based on supported domains
The code that will verify that the customer is allowed to sign up to a close loop reward scheme
The date that the account has signed up (if not specified, defaults to current date)
Responses
OK
Body
The reward scheme identifier
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"
}{id}/reward_schemes/{reward_scheme_id}Sign out the account from a specific reward scheme
Path variables
The account (identifier) that will be signed off from the reward scheme
The reward scheme (identifier) that the account has signed off
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DXD HTTP/1.1
authorization: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK {id}/merchantsAdd a set of new merchants for automatic spends for that account
Path variables
The account (identifier) whose merchant preferencees will be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
Defines a list of merchants that are authorised to perform automatic awards spending for that account
The organisation identifier that should be authorised to perform automatic awards spending
Defines whether the merchant is setup for automatic spend on the next visit
Responses
OK
Body
A list of merchants that are authorised to perform automatic awards spending for that account
The organisation identifier
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"
}
]
}{id}/merchants/{merchant_id}Remove an exisintg merchant from an account’s automatic spend preferences
Path variables
The account (identifier) whose reward attributes will be updated
The merchant (identifier) that will be removed from the spend preferences
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/merchants/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
authorization: 4AD9C84FA60F9FE407140E20F707726A
HTTP/1.1 200 OK {id}{id}{id}/balancesRequest headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The contact that owns the Wallet
The Wallet’s code. If not specified, then a unique and random 16-digit code is assigned to the Wallet.
The wallet’s primary currency. If not specified, then the base currency of the Cloud operator is used
["TOPUP"]{id}Updates a single Wallet.
Path variables
The unique identifier of the Wallet to be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted