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 BackOffice API uses either API keys to authenticate requests or an authentication JWT token obtained from a user successful logging in
API keys can be accessed and managed in the CRM.COM Dashboard. Such API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth
All API requests must be made over HTTPS. API requests made over plain HTTP or without authentication will fail. API keys authentication is made using -H “api_key : crm_test_;dwfwgiuhjr412edws”, while User Bearer Auth is achieved using -H “Authorization: Bearer JWT_TOKEN”
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 uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request
- 2xx success status codes confirm that your request worked as expected
- 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
- 5xx error status codes are rare and indicate an error with Stripe’s servers
Please note that some 4xx errors that could be handled programmatically (e.g. a contact already exists) contain the following informaiion
- HTTP Code (programmatic consumption)
- Message (human-readable)
- Attribute (attribute that caused the error)
Below is a list of our common error codes that can be returned, along with additional information about how to resolve them
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
{id}/accounts{id}/accounts{id}{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 exists) will be provided
Responses
OK
Body
The account identifier
POST https://stagingapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1
Content-Type: application/json
{
"classification_id": "4AD9C84FA60F9FE407140E20F707726A",
"currency_code": "USD",
"is_primary": true,
"billing_address_id": "4AD9C84FA60F9FE407140E20F707726A"
}
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 the primary account of the contact
The account name
The Account number
The account’s life cycle state
The account’s currency
The account’s 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 billing address of the account which is the same as one of the contact’s addresses
The account’s wallet information (if available)
The wallet identifier
The wallet’s life cycle state
GET https://stagingapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"accounts": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"is_primary": true,
"name": "Default",
"number": "AC123456",
"life_cycle _state": "ACTIVE",
"currency_code": "",
"classification": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "VIP"
},
"balance": 200,
"credit_limit": 100,
"overdue_amount": 50,
"billing_address_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"wallet": {
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"code": "1234567898767543",
"balance": 200.2,
"currency_code": "EUR",
"life_cycle_state": "CANCELLED"
}
}
]
}{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}/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/wallet balance will get transfered, in case of Termination
Responses
Successful Request
Body
The unique identifier of the account
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"
}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, unspecified = all
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.)
Transaction type
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
Contact details
The unique identifier of the contact that owns the financial transaction
The full name of the contact that owns the transaction
The unique code of the contact that owns the transaction
Details of the (organisation) merchant account owning the transaction
Merchant organisation unique identifier
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": "PAYMENT",
"reference_code": "A09967",
"entity_number": "CN88942",
"contact": {
"id": "AK89E31269B76D7A65ACCE45B2E68DFD",
"name": "John Smith",
"code": "HL095568"
},
"amount": 9.99,
"currency": "EUR",
"life_cycle_state": "POSTED",
"description": "Credit adjustment by 10 EUR"
}
],
"pages": {
"page": 2,
"size": 20,
"total": 5124
}
}{id}/financials{id}/members{id}/members/{member_id}{id}/members/{member_id}{id}/members{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 ID of the latest closed accounting period
The name of the account’s latest accounting period
The opening balance brought forwards after the latest closed accounting period
The unique identifier of the Account classification
The name of the Account classification
The account’s wallet information (if available)
The wallet’s unique identifier
A unique 16-digit code that if not provided, it is auto-generated
The total balance of the wallet
The commerce balance of the wallet
The open balance of the wallet
The wallet’s life cycle state
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 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, PayPal and Account). Defaults to the primary payment method, if any.
The id of the billing address
GET https://stagingapi.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,
"accounting_period_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"accounting_period_name": "OCTOBER2018",
"opening_balance": 100.5,
"classification": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "VIP"
},
"wallet": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "W00123456",
"balance": 150.5,
"commerce_balance": 98,
"open_balance": 1,
"life_cycle_state": "EFFECTIVE",
"minimum_balance": 9,
"limit_rules": [
{
"minimum_amount": 100.5,
"maximum_amount": 200,
"period": "ANNUAL",
"transaction_type": "TRANSFER"
}
],
"auto_topup": {
"threshold": 10.5,
"amount": 10.5,
"payment_method": "PAYPAL",
"payment_method_id": ""
}
}
],
"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}/membersAdd new member on an account group.
Path variables
The account identifier to which the new member will be added to its group
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The member account that will join the group
The funding scope that the account joins the group
The funded products of the member account
Responses
Successful Request
Body
The unique identifier of the account
POST https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/members HTTP/1.1
Content-Type: application/json
{
"member_account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"funding_scope": "PARTIALLY",
"products": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
],
"product_types": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
],
"product_families": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": ""
}{id}/members/{member_id}Update a member of this account group
Path variables
The account identifier that the member belongs to
The member account identifier to be updated
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The funding scope that the account joins the group
The funded products of the member account
Responses
Successful Request
Body
The unique identifier of the account
PUT https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/members/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
Content-Type: application/json
{
"funding_scope": "FULLY",
"products": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
],
"product_types": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
],
"product_families": [
"CAD1E31269B76D7A65ACCE45B2E68DFD"
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": ""
}{id}/members/{member_id}Remove a member account from an account group
Path variables
The account identifier that the member belongs to
The member account identifier to be removed
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Responses
Successful Request
Body
The unique identifier of the account
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/members/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}{id}/membersLists the members of an account
Path variables
The account identifier for which the members will be retrieved
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The member account’s unique identifier
The member account’s number
The funding scope that the account joins the group
The unique identifier of the funded product
The SKU of the funded product
The unique identifier of the funded product type
The name of the funded product type
The unique identifier of the funded product family
The name of the funded product family
Responses
Successful Request
Body
The unique identifier of the account
GET https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/members HTTP/1.1
Content-Type: application/json
{
"members": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"number": "AC123456",
"funding_scope": "PARTIALLY",
"products": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"sku": "ABC123"
}
],
"product_types": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "FOOD"
}
],
"product_families": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "COFFEE"
}
]
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": ""
}{id}/wallets{id}{id}/actions{id}/balances{id}/walletsAdd a new wallet for an existing 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 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
OK
Body
The wallet identifier
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"
}{id}Update the wallet of an account
Path variables
The wallet 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 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 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, PayPal and Account). Defaults to the primary payment method, if any.
Responses
OK
Body
The wallet identifier
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"
}{id}/actionsChange the life cycle state of the Wallet
Path variables
The wallet 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
Defines the life cycle state of the wallet. If selected, then all of the above will not be taken into consideration
Responses
Successful Request
Body
The unique identifier of the wallet
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"
}{id}/balancesGet the wallet’s balances split per spend condition
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
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
The organsiation identifier
The name of the organisation
The location of the organisation
Information about the organisation’s location
The name of the location
The address of the location
Additional address information about the location
The state/province/county of the location
The town/city of the location
The postal code of the location
The country code of the location
The latitude of the location
The longitude of the location
The Google textual identifier that uniquely identifies a location
The products that the amount can be spent for
The type of the ID to be provided
The ID of the product (based on the type provided)
The name of the product
The descrtipion of the product
The time when the amount can be spent
The month as a condition (1-12)
The day of the week as condition (1-7), 1 is Sunday
The start time of the day in 24 Hour format
The end time of the day in 24 Hour format
Defines the amounts expiring in periods. Available only if the parameter include_expiration is set to true
The amount that will expire in up to 30 days
The amount that will expire from 30 to 60 days
The amount that will expire from 60 to 90 days
The amount that will expire in more than 90 days
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 a wallet debit or credit journal entry
Request headers
Authorization Token
The secret api key required for API calls to ensure that the client is trusted
Request body
The unique identifier for which the journal entry will be created
The amount of the journal
The type of the journal
The description of the journal
The unique identifier of the related spend condition
The valid from date
The valid to date
The date and time when the journal actually created
Allows a wallet debit journal to take the wallet balance below zero. By default, the wallet balance cannot go below zero.
Responses
OK