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.
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 contacts, 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 404 Not Found
{
"status": 404,
"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 is an account
{id}/accounts{id}{id}/accounts{id}/life_cycle_state{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
Sets the Account’s Payment Terms.
Responses
OK
Body
The account identifier
PUT https://sandbox.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,
"payment_terms_id": "4AD9C84FA60F9FE407140E20F707726A"
}{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
Retrieve accounts with a specific life cycle state
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
The account’s Payment Terms
Wallet related to the Account
Wallet identifier
Wallet code
Wallet total balance
Currency code
Wallet’s state
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": "c8d83493-3f50-40df-adb0-762ec5f41863",
"name": "Delivery Purchase"
},
"balance": 200,
"credit_limit": 100,
"overdue_amount": 50,
"payment_terms": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "Net 7"
},
"wallet": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "9005455565111112",
"balance": 9.99,
"currency_code": "EUR",
"life_cycle_state": "EFFECTIVE"
}
}
]
}{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"
}{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
The account’s payment terms
Payment terms identifier
Payment terms name
The account’s related Wallet
Wallet identifier
Wallet code
The wallet life cycle state
Total balance
Open balance
Commerce balance
The minimum wallet balance threshold. If not provided, the global rules apply
The minimum amount allowed
The maximum amount allowed
The period for which the limit is applied
The wallet transaction type for which the limit is applied
Sets the threshold for the auto topup to be performed
The amount to get topped up
Indicates the method of collecting money
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.
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": "TERMINATED",
"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"
},
"payment_terms": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "Net 7"
},
"wallet": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "9000004434321111",
"life_cycle_state": "TERMINATED",
"balance": 9.99,
"open_balance": 5.45,
"commerce_balance": 4.54,
"currency_code": "EUR",
"minimum_balance": 5.99,
"limits": [
{
"minimum_amount": 5.99,
"maximum_amount": 99.99,
"period": "MONTHLY",
"transaction_type": "CREDIT"
}
],
"auto_topup": {
"threshold": 99.99,
"amount": "9.99",
"payment_method": "CARD",
"payment_method_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
}
}{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
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}/wallets{id}/walletsAdds a new Wallet to an Account. This is allowed only if the account is not related to any wallet or if the account’s related wallet was previously Terminated. So an Account can only be related to a single Effective Wallet at a time.
Path variables
Account identifier
Request body
The minimum wallet balance threshold. If not provided, the global rules apply
Defines the limit rules applied on specific wallet. If not provided, the global rules apply
The maximum amount allowed
The wallet transaction type for which the limit is applied
The period for which the limit is applied
Responses
Body
The Wallet identifier
POST https://sandbox.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/wallets HTTP/1.1
Content-Type: application/json
{
"minimum_balance": 10.99,
"limit_rules": [
{
"limit_amount": 100.99,
"transaction_type": "DEBIT",
"period": "MONTHLY"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}{id}{id}/actions{id}/commerce_balances{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
Request body
Wallet’s auto top up settings.
The wallet’s minimim balance threshold that triggers this rules once it is reached
The auto top up’s amount
The payment method from which funds will be automatically retrieved
The contact’s payment method identifier.
["TOPUP"]Responses
Body
The unique identifier of the updated Wallet
PUT https://sandbox.crm.com/backoffice/v1/wallets/4dc0809f-ed91-4b68-b912-5bd6064d901e HTTP/1.1
Content-Type: application/json
{
"auto_topup": {
"threshold": 0.01,
"amount": 10.5,
"payment_method": {
"type": "CARD",
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
}
},
"termed_topup": {
"amount": 10.5,
"frequency": {
"period": "MONTHS",
"value": 1
},
"topup_day": {
"day_of_month": 1,
"day_of_week": "MONDAY"
},
"payment_method": {
"type": "",
"id": ""
}
},
"limit_rules": [
{
"name": "VIP",
"maximum_amount": 9.99,
"maximum_number": 10,
"period": "ANNUAL",
"transaction_type": [
"TOPUP"
]
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "3ac0809f-ed91-4b68-b912-5bd6064d901e"
}{id}/actionsUpdates an existing Wallet’s state
Path variables
Wallet identifier
Request headers
Authorization Token
The public api key required for API calls to identify the organisation
Request body
Defines the life cycle state of the wallet. If selected, then all of the above will not be taken into consideration
Responses
Body
The updated wallet’s identifier
POST https://sandbox.crm.com/backoffice/v1/wallets/234fbc54-bc32-1990-ce59-76c45e6377a8/actions HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json
{
"action": "TERMINATED"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "234fbc54-bc32-1990-ce59-76c45e6377a8"
}{id}/commerce_balancesRetrieves a wallet’s business balance breakdown. The balance is returned per spend condition which credited the wallet’s business balance, along with the spend condition’s details
Path variables
The unique identification of the wallet whose balance spend conditions will be retrieved.
Request parameters
The id of a specific spend condition (optional). If not provided then all spend conditions are retrieved
If set to true, then the expiration information will also be retrieved
If not specified, then the balance breakdown of the wallet’s primary currency will be returned by default.
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The spend condition group identifier
The name of the spend condition group
The amount that is allocated to the specified spend condition
The organisations where the amount can be spent at