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 back-office 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 API uses either API keys to authenticate requests, or an authentication JWT token obtained from a user logging in successfully.
You can view and manage your API keys in the CRM.COM Dashboard.
Your 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.
-H “api_key : crm_test_;dwfwgiuhjr412edws”
If you need to authenticate a Admin User bearer auth, use -H “Authorization: Bearer JWT_TOKEN”
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
API requests without authentication will also fail.
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}{id}/consentsCreate a new contact, either a new Person or a Company
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The contact identifier, if not supplied one will be generated
User readable code for the contact
Type of contact support types include Person and Company.
Company Name if the Contact represents a company, required attribute if the type is a Company.
The title of the contact. Applicable only if the type is PERSON
The first name of the contact. Applicable and mandatory only if the type is PERSON
The middle name of the contact. Applicable only if the type is PERSON
The last name of the contact. Applicable and mandatory only if the type is PERSON
The contact’s preferred language for communication
The contact’s unique statutory number
Notes for the contact
The contact authorisation setting for direct marketing
The contact authorisation setting for affiliate marketing
If set to true, then a single account is created for the contact usig the system’s default settings and no further input is needed.
The contact’s category. The category’s ID or code should be specified
The category’s GUID
The category’s code
Information about the contact’s demographic. Applicable only if the contact type is PERSON
The gender of the contact
The country code for the country of residence
Information about the contact’s passport
The passport number
The passport’s issue country code
The passport’s expiration date
Information about the contact’s id. Applicable only if the contact is type of PERSON
The id number
The id’s issue country code
The id’s expiration date
The contact’s name day. Applicable only if the contact is type of PERSON
The month of the name day
The day of the name day
Information about the contact’s data of birth. Applicable only if the contact is type of PERSON
The birtdate year
The borthdate month
The borthdate day
Information about the company’s profile. Applicable only if contact_type is COMPANY
The company’s Industry. Either the id or the code should be specified.
The industry’s identifier
The industry’s code
The company’s industry sectors. Multiple industry sector can be specified. Either the id or the code should be specified for each sector
The industry sector’s identifier
The industry sector’s code
The profile year
The annual turnover
The date that the company was established on
The company’s number of employees
The company’s registration number
The company’s registrationc country code
The company’s tax reference number
The company VAT registration numnber
Information about the contact’s addresses
The address type
Primary address for Billing or Communication
Optional basic account settings for a financial contact
The account name
Indicates the primary account of the contact
The account’s credit rating
The account’s credit limit
The account’s currency
Defines whether the account is TAX exempt
The account’s Classification
The account classification identifier
The account classification’s code
The custom field’s unique key
The custom field’s value
Responses
The request has succeeded
Body
The contact identifier
Create a contact for a physical person
POST /contacts HTTP/1.1
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123",
"contact_type": "PERSON",
"title": "Sir",
"first_name": "Louis",
"middle_name": "Aloz",
"last_name": "Kozior",
"preferred_language_code": "ENG",
"statutory_number": "231224-1222000",
"notes": "Notes",
"direct_marketing": "true",
"affiliate_marketing": "false",
"create_default_account": true,
"category": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123"
},
"demographics": {
"gender": "MALE",
"country_of_residence": "USA",
"passport": {
"passport_number": "K)123456",
"issue_country_code": "GRC",
"expiration_date": 129876564
},
"id_details": {
"id_number": "132465",
"issue_country_code": "CYP",
"expiration_date": 1129876567
},
"name_day": {
"month": 4,
"day": 12
},
"date_of_birth": {
"year": 1999,
"month": 12,
"day": 31
}
},
"addresses": [
{
"address_type": "POBOX",
"is_primary": "true",
"care_of": "",
"address_line_1": "",
"address_line_2": "Thomas V",
"state_province_county": "Active",
"town_city": "",
"postal_code": "",
"country_code": "CYP"
}
],
"phones": [
{
"phone_type": "CUSTOM2",
"is_primary": true,
"country_code": "CYP",
"number": "238065437"
}
],
"emails": [
{
"email_type": "PERSONAL",
"is_primary": true,
"email_address": "johndoe@crm.com"
}
],
"accounts": [
{
"name": "",
"is_primary": true,
"credit_rating": "AA",
"credit_limit": 250,
"currency_code": "GBP",
"is_tax_exempt": true,
"classification": {
"id": "",
"code": "VIP"
}
}
],
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}Create a contact for a company
POST /contacts HTTP/1.1
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123",
"contact_type": "COMPANY",
"company_name": "Good Burger",
"preferred_language_code": "ENG",
"statutory_number": "231224-1222000",
"notes": "Notes",
"direct_marketing": "true",
"affiliate_marketing": "false",
"create_default_account": true,
"category": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123"
},
"company_profile": {
"industry": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "IT"
},
"industry_sectors": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "INDS1234"
}
],
"profile_year": 2019,
"annual_turnover": 450000,
"established_on": 98765342,
"number_of_employees": 200,
"registration_number": "123456",
"registration_country": "CYP",
"tax_reference_number": "TAX1234",
"vat_registration_number": "VAT1234"
},
"addresses": [
{
"address_type": "HOME",
"is_primary": "true",
"care_of": "",
"address_line_1": "",
"address_line_2": "Thomas V",
"state_province_county": "Active",
"town_city": "",
"postal_code": "",
"country_code": "CYP"
}
],
"phones": [
{
"phone_type": "CUSTOM4",
"is_primary": true,
"country_code": "CYP",
"number": "238065437"
}
],
"emails": [
{
"email_type": "CUSTOM3",
"is_primary": true,
"email_address": "johndoe@crm.com"
}
],
"accounts": [
{
"name": "",
"is_primary": true,
"credit_rating": "B",
"credit_limit": 250,
"currency_code": "GBP",
"is_tax_exempt": true,
"classification": {
"id": "",
"code": "VIP"
}
}
],
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}Update A Contact, it is possible to supply a partial body so that only supplied items will be updated.
Path variables
internal Unique ID of Contact as specified on request or response of create
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The contact’s unique code
Company Name if the Contact represents a company, required attribute if the type is a Company.
The title of the contact. Applicable only if the type is PERSON
The first name of the contact. Applicable and mandatory only if the type is PERSON
The middle name of the contact. Applicable and mandatory only if the type is PERSON
The last name of the contact. Applicable and mandatory only if the type is PERSON
The contact’s category. Either id or code should be specified
The contact category GUID
The cotnact category code
A company’s profile. Applicable only if contact_type is COMPANY
The company’s Industry. Either id or code should be specified
The industry’s GUID
The industry’s code
The company’s Industry Sectors. Either id or code should be specified per industry sector
The custom field’s unique key
The custom field’s value
Responses
OK
Body
The updated contact’s GUID
Examples
PUT /contacts/{id} HTTP/1.1
Content-Type: application/json
{
"code": "ABC-123",
"title": "Sir",
"first_name": "Louis",
"middle_name": "Aloz",
"last_name": "Kozior",
"preferred_language_code": "ENG",
"category": {
"id": "",
"code": "VIP"
},
"notes": "Notes",
"statutory_number": "EF12345",
"demographics": {
"gender": "FEMALE",
"country_of_residence": "",
"passport": {
"passport_number": "",
"issue_country_code": "GRC",
"expiration_date": 129876567
},
"id_details": {
"id_number": "",
"isssue_country_code": "CYP",
"expiration_date": 1
},
"name_day": {
"month": 10,
"day": 4
},
"date_of_birth": {
"year": 2018,
"month": 10,
"day": 16
}
},
"addresses": [
{
"id": "",
"address_type": "CUSTOM2",
"care_of": "",
"is_primary": "true",
"address_line_1": "",
"address_line_2": "Thomas V",
"state_province_county": "California",
"town_city": "",
"postal_code": "",
"country_code": "CYP"
}
],
"phones": [
{
"id": "",
"phone_type": "CUSTOM2",
"is_primary": true,
"country_code": "44",
"number": "238065437"
}
],
"emails": [
{
"id": "",
"email_type": "CUSTOM3",
"is_primary": true,
"email_address": "bill@gmail.com"
}
],
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}Update multiple contacts in bulk mode. Available from CRM.COM R18.2.0
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
A list containing the contacts to be updated. Either the id or the code mus tbe speficied in each Web API call
The contact to be updated. Either the id or the code should be specified
The contact’s GUID
The contact’s code
The category’s unique identifier
The cateogry’s code
The custom field’s unique key
The custom field’s value
Responses
OK
Body
A unique identifier of the Web API call which can be used for triggering the webhook and relate the api request to the webhook request (enables integrator to match the api request with the webhook request).
PUT /contacts/ HTTP/1.1
Content-Type: application/json
{
"contacts": [
{
"contact": {
"id": "3452AB543FF03",
"code": "ABC-12345"
},
"category": {
"id": "3420001ADF354",
"code": "VIP"
},
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": ""
}{id}/consentsUpdates the Consent state of the Contact
Path variables
The contact identifier that will be updated
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The consent state to be updated
Responses
Successful Request
Body
The unique identifier of the contact
PUT /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/consents HTTP/1.1
Content-Type: application/json
{
"consent_state": "WITHDRAWN"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}{id}/credentials{id}/credentialsCreate a set of credentials for an existing customer
Path variables
The contact that should be updated
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The contact’s username
The contact’s password
Responses
The request has succeeded
Body
The credentials identifier
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/credentials HTTP/1.1
Content-Type: application/json
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
{
"username": "j_doe@crm.com",
"password": "12345"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}{id}/wallet_transactions{id}{id}/expiration_date{id}/wallet_transactions/{transaction_id}Retrieves the available vouchers
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
The voucher classification
The voucher’s life cycle state
The type of the vouchers to be retrieved
The vouchers category
The number of the voucher to be retrieved
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
OK
Body
The voucher identifier
The contact that owns the voucher
The voucher number
The voucher classification
The life cycle state of the voucher
The vouchers category
The value of the voucher. Can be empty
An extra added value of the voucher. Can be empty
The minimum value allowed for the voucher (if value is empty)
The maximum value allowed for the voucher (if value is empty)
The number of UOT that the voucher amount will be valid for
The UOT that the voucher amount will be valid for
The actual expiration date of the voucher
The page number
The number of records per page
The total number of records overall
GET /vouchers HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"contact_id": "6A24D2B5E44F44B28451FE021FCAD51E",
"number": "V0123456",
"classification": "REFUND",
"life_cycle_state": "ACTIVATED",
"category": "IDENTIFIES_CUSTOMER",
"value": 200,
"extra_added_value": 10,
"minimum_value": 50,
"maximum_value": 1,
"validity_period": 1,
"validity_UOT": "YEAR",
"expiration_date": "1585040255",
"paging": [
{
"page": 2,
"size": 20,
"total": 5214
}
]
}{id}/wallet_transactionsRetrieves the wallet transactions of a specific contact
Path variables
The contact identifier whose wallet transactions will be retrieved
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
The date that the retrieved wallet transactions were created
The wallet transaction classification
The wallet transaction life cycle state
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
OK
Body
The wallet transaction identifier
The accout owner’s GUID
The wallet of the transaction
The wallet transaction number
The wallet transaction classification
The life cycle state of the wallet transaction
The amount of the wallet transaction in system currency
An extra added amount in wallet currency
The date that the wallet transaction was made
The wallet transaction expiration date
The user that created the wallet transaction
The unique identifier of the user
The date and time that the wallet transaction was created
The page number
The number of records per page
The total number of records overall
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/wallet_transactions HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
"wallet_id": "6A24D2B5E44F44B28451FE021FCAD51E",
"number": "WT123456",
"classification": "TRANSFER",
"life_cycle_state": "VOID",
"amount": 200,
"extra_added_amount": 1,
"transaction_date": "1573545935",
"expiration_date": "1573545935",
"created_by": {
"id": "6A24D2B5E44F44B28451FE021FCAD51E"
},
"created_on": "1573545935",
"paging": [
{
"page": 2,
"size": 20,
"total": 5124
}
]
}{id}Uses a single voucher
Path variables
The unique identifier of the voucher to be used
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The secret number of the voucher to be used
The value of the voucher to be used. Applicable only if the voucher type allows variable values
The custom field’s unique key
The custom field’s value
Responses
OK
Body
The used voucher ID
POST /vouchers/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
Content-Type: application/json
{
"secret_number": "S0123456",
"value": 200,
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}/expiration_datePath variables
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The new expiration date of the voucher
Responses
OK
POST /vouchers/{id}/expiration_date HTTP/1.1
Content-Type: application/json
{
"expiration_date": "1585040255"
}
HTTP/1.1 200 OK {id}/wallet_transactions/{transaction_id}Voids a single wallet transaction
Path variables
The unique identification of the contact owning the wallet transaction
The unique identification of the wallet transaction to be voided
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The custom field’s unique key
The custom field’s value
Responses
OK
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/wallet_transactions/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
Content-Type: application/json
{
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}/cancel{id}/walletsRequest headers
The secret api key for API calls to ensure that the client is trusted
Request body
The wallet’s GUID
The accout owner’s GUID
The voucher of type identifies customer that will be used to credit the wallet and then identify the wallet and debit it
In case that the identification is a voucher then the secret number may be required
The amount to be debited
The type of the debit wallet transaction
The consumption validity date for the allotted amount. If not specifried the current date is used.
The product related with the wallet transaction allotment
The business unit related with the wallet transaction allotment
The custom field’s unique key
The custom field’s value
Responses
OK
Body
The ID of the wallet transaction created
POST /wallets/debits HTTP/1.1
Content-Type: application/json
{
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
"voucher_number": "V0123456",
"secret_number": "1234",
"amount": 1234.56,
"type": "6A24D2B5E44F44B28451FE021FCAD52E",
"allotments": {
"consumption_date": 1578580663,
"product_identifier": "6A24D2B5E44F44B28451FE021FCAD52E",
"business_unit_identifier": "6A24D2B5E44F44B28451FE021FCAD52E"
},
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}/cancelCancels a single wallet
Path variables
The wallet identifier to be cancelled
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The custom field’s unique key
The custom field’s value
Responses
OK
POST /wallets/CAD1E31269B76D7A65ACCE45B2E68DFD/cancel HTTP/1.1
Content-Type: application/json
{
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}/walletsRetrieves the wallets of a specific contact
Path variables
The contact identifier whose wallets will be retrieved
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
OK
Body
The wallet identifier
The accout owner’s GUID
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/wallets HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"account_id": "6A24D2B5E44F44B28451FE021FCAD52E",
"number": "W000001",
"balance": 1234.56,
"alternative_balance": 231.54,
"currency_code": "EUR",
"alternative_currency_code": "PTS",
"conditional_balance": 25.34,
"conditional_alternative_balance": 1.52,
"unconditional_balance": 4.75,
"unconditional_alternative_balance": 4.57,
"amount_on_hold": 5.98,
"alternative_amount_on_hold": 2.34
}Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The wallet’s GUID
The wallet transaction classification
The amount to be credited or debited
The custom field’s unique key
The custom field’s value
Responses
Body
The ID of the wallet transaction created
POST /wallets/adjust HTTP/1.1
Content-Type: application/json
{
"id": "6A24D2B5E44F44B28451FE021FCAD51E",
"classification": "CREDIT",
"amount": 123.45,
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
]
}{id}/payment_methods{id}/payment_methods/{payment_method_id}{id}/payment_methods/{payment_method_id}{id}/payment_methods{id}/payment_methodsAdd a new payment method for a contact supports BANK, CREDIT / DEBIT cards, or Payment Gateways such as Paypal.
Path variables
The contact identifier (GUID) or code that will be updated
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The payment method identifier, if not specified it will be auto generated
The payment method’s type
The bank details.Required and applicable if the payment method is set to BANK
The bank account number. Either the bank account number or IBAN must be specified
The IBAN code. Either the bank account number or IBAN must be specified
The card’s main information. Required and applicable if the payment method type is CARD
The card’s name
The card’s brand
The Card number.
The first 6 digits of the card.
The last 4 digits of the card.
Encrypted hashed version of the card for comparison only as a CIM
If set to True, then the card holder’a address is automatically set using the account’s billing address
The payment gateway that tokenized the card
If using the Generic Gateway specify the implementation code given to you by CRM.COM
The card token
Use a payment gateway with an account such as PAYPAL. Required and applicable if payment method is set to PAYPAL
Responses
OK
Body
The payment method identifier
Add a Card payment method
POST /contacts/423423424234/payment_methods HTTP/1.1
Content-Type: application/json
{
"id": "34234234-34343",
"payment_method_type": "CARD",
"notes": "some notes",
"card": {
"name": "default card",
"brand": "AMERICANEXPRESS",
"card_number": "492942******7004",
"first6": "",
"last4": "",
"fingerprint": "Xt5EWLLDS7FJjR1c",
"expiration_month": 1,
"expiration_year": 2020,
"is_default": true,
"card_holder_details": {
"card_holder_name": "Mrs M Smith",
"address_line_1": "address_line_1",
"address_line_2": "address_line_2",
"address_city": "address_city",
"address_zip": "address_zip",
"address_state": "address_state",
"address_country": "address_country",
"use_billing_address": "false"
},
"card_gateway_token": [
{
"gateway": "STRIPE,BRAINTREE,PAYEEZY,GENERIC",
"gateway_code": "",
"token": "123434556232134324"
}
]
}
}{id}/payment_methods/{payment_method_id}Update an existing payment method for a contact
Path variables
The contact identifier whose payment method will be updated
The payment method that will be updated
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The card’s main information. Required and applicable if the payment method type is CARD
The card’s name
The card’s brand
Card number with obfsucated numbers. Either the card number or the first 6 and last 4 digits must be specified
The first 6 digits of the card. Either the card number or the first 6 and last 4 digits must be specified
The last 4 digits f the card. Either the card number or the first 6 and last 4 digits must be specified
Encrypted hashed version of the card for comparison only as a CIM
If set to True, then the card holder’a address is automatically set using the account’s billing address
The payment gateway that tokenized the card
If using the Generic Gateway specify the implementation code given to you by CRM.COM
The card token
Responses
OK
Body
The payment method identifier
Examples
PUT /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/payment_methods/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
Content-Type: application/json
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
{
"card": {
"name": "default card",
"brand": "MASTERCARD",
"card_number": "492942******7004",
"first6": "",
"last4": "",
"fingerprint": "Xt5EWLLDS7FJjR1c",
"expiration_month": 1,
"expiration_year": 2020,
"is_default": true,
"card_holder_details": {
"card_holder_name": "Mrs M Smith",
"address_line_1": "address_line_1",
"address_line_2": "address_line_2",
"address_city": "address_city",
"address_zip": "address_zip",
"address_state": "address_state",
"address_country": "address_country",
"use_billing_address": "false"
},
"card_gateway_token": [
{
"gateway": "STRIPE,BRAINTREE,PAYEEZY,GENERIC",
"gateway_code": "",
"token": "123434556232134324"
}
]
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}{id}/payment_methods/{payment_method_id}Removes a single payment method from the contact
Path variables
The contact identifier whose payment method will be removed
The payment method identifier that will be removed
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
OK
DELETE /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/payment_methods/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK {id}/payment_methodsList of Payment method allocated to subscriber.
Path variables
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The payment method identifier
The username of the payment gateway token for Paypal payment methods
The basic card information for Card payment methods
The card’s brand name
Masked card number
The last four digits of the card
The card’s funding type. Available from CRM.COM-R18.2.0
The card’s classification. Available from CRM.COM R18.2.0
The card’s classification unique identifier
The card’s classification name
The accounts that support the retrieved payment method
The account’s GUID
The account’s number
The account’s name
Examples
GET /contacts/{id}/payment_methods HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "f21abc565467897543bcdefa12",
"bank": [
{
"sort_code": "20-02-53",
"account_number": "001002001",
"bank": "Barclays",
"branch": "Ascot",
"iban": "0143240434320434"
}
],
"payment_method_type": "CARD",
"payment_gateway_token": "anemail@email.com",
"card": {
"brand_name": "AMERICANEXPRESS",
"card_number": "",
"last4": "",
"funding_type": "PREPAID",
"classification": {
"id": "55345ABC34EF",
"name": "Students"
}
},
"accounts": [
{
"id": "",
"number": "",
"name": ""
}
]
}{id}/cancelCreate a new purchase customer event in posted life cycle state
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The customer event unique Identifier
The contact id that the customer event is created for. Either contact_id or cim must be specified.
The value for a single contact identification medium representing the customer event is created for. Either contact_id or cim must be specified.
The external system’s reference number that submitted the customer event, the value must be unique and can be used to get or delete a transaction
The classification of the purchase event
The classification’s identifier
The classification’s code
The date that the customer event was performed
The currency code that the customer event is created against
The purchased products for this customer event
ID of Family
The purchased product code
The purchased product net amount
The purchased product vat amount
The purchased product total amount (net and vat amount)
The purchased product quantity
Information related with the spend request that should be created as part of the purchase customer event
The amount to be spent by the specified spend request in system currency
The amount to be spent by the specified spend request in alternative currency, including points, stickers etc.
Either tap id or code must be specified
The business unit tap identifier that the customer event was submitted from.
The business unit tap code that the customer event was submitted from
Either tap id or code must be specified
The business unit tap identifier that the customer event was submitted from.
The business unit tap code that the customer event was submitted from
Responses
The request has succeeded
Body
The customer event identifier
POST /purchases HTTP/1.1
Content-Type: application/json
{
"id": "CEEE83D6E0804A30966F684B0269AD91",
"contact_id": "CEEE83D6E0804A30966F684B0269AD91",
"cim": "4A30966F684B0269AD91",
"reference_number": "RF000001",
"classification": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "PCE1234"
},
"payment_medium_identifier": "42424242",
"performed_on": 1572423477,
"currency_code": "EUR",
"products": [
{
"product_sku": "FREDESPR001",
"net_amount": 14.15,
"tax_amount": 1.04,
"total_amount": 15.19,
"quantity": 2
}
],
"spend_request": {
"amount": 2.12,
"alternative_amount": 1.75
},
"merchant_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "EK123456"
},
"outlet_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "CD123456"
}
}{id}/cancelCancels an existing posted purchase customer event
Path variables
The purchase’s GUID
Request headers
The secret api key for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The customer event identifier
POST /purchases/CEEE83D6E0804A30966F684B0269AD91/cancel HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CEEE83D6E0804A30966F684B0269AD91"
}Search for purchases
Request parameters
The contact identifier who performed the purchase
The purchase’s reference number
The date from which the purchase was performed.If not specified, then the last 10 purchases will be returned
The date until which the purchase was performed
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
The secret api key for API calls to ensure that the client is trusted
Responses
Successful Request
Body
The purchase’s GUID
The purchase’s number
The purchase’s reference number
The purchase’s life cycle state
The purchase’s total amount
The date on which the purchase was performed
The business unit name at which the purchase was performed
The busienss unit GUID at which the purchase was performed
The account agianst which the purchase was submitted
The purchase event’s classification name
The page number
The number of records per page
The total number of records overall
GET /purchases HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK
Content-Type: application/json
{
"purchases": [
{
"id": "CEEE83D6E0804A30966F684B0269AD91",
"number": "1234",
"reference_number": "REF1234",
"life_cycle_state": "POSTED",
"total_amount": 7,
"performed_on": 1576486645,
"performed_by_unit_name": "Bravo Coffee",
"performed_by_unit_id": "CEEE83D6E0804A30966F684B0269AD91",
"account_id": "CEEE83D6E0804A30966F684B0269AD91",
"classfication_name": "Card Purchase"
}
],
"paging": {
"page": 2,
"size": 20,
"total": 5124
}
}Ad hoc return of physical goods
Request headers
The secret api key for API calls to ensure that the client is trusted
Request body
The contact id that the customer event is created for (either contact_id or cim must be specified)
The value for a single contact identification medium representing the customer event is created for (either contact_id or cim must be specified)
The purchased amount of goods that are returned
The currency code
Information about the merchant transaction acquiring point
The business unit tap identifier that the customer event was submitted from (either id or code must be specified)
The business unit tap code that the customer event was submitted from (either id or code must be specified)
Information about the outlet transaction acquiring point
The business unit tap identifier that the customer event was submitted from (either id or code must be specified)
The business unit tap code that the customer event was submitted from (either id or code must be specified)
The ad hoc return reference number
Responses
The request has succeeded
Body
The purchase identifier that ad hoc return is performed against
Perform Ad Hoc Return & return Purchase Identifer on which such return is applied
POST /purchases/ad_hoc_return HTTP/1.1
Content-Type: application/json
{
"cim": "4A30966F684B0269AD91",
"amount": 123.45,
"currency_code": "EUR",
"merchant_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "EK123456"
},
"outlet_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "CD123456"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "37ed4a1a-0e8f-4691-a8a0-636aea6e47c5"
}Perform Ad Hoc Return & return just 200 as no purchase was found
POST /purchases/ad_hoc_return HTTP/1.1
Content-Type: application/json
{
"cim": "4A30966F684B0269AD91",
"amount": 123.45,
"currency_code": "EUR",
"merchant_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "EK123456"
},
"outlet_tap": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"code": "CD123456"
}
}
HTTP/1.1 200 OK List of merchants and participating schemes or filtered by scheme
Request parameters
The reward scheme identifier to which the merchant participates
Defines whether reward scheme information should be retrieved
Defines whether venue information should 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
The secret api key for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The business unit (merchant) identifier
The business unit (merchant) code
The business unit (merchant) name
The business unit (merchant) description
Indicates whether the business unit (merchant) has not other business units as children (outlets)
Information about the reward schemes that the business unit participates (retrieved only if requested)
The reward scheme identifier
The reward scheme name
The reward scheme code
Information about the transaction acquiring points
The tap identifier
The tap name
The tap code
Details about the venues of the merchant (retrieved only if requested)
The business unit (venue) identifier
The business unit (venue) name
Details about the business unit (venue) taps
The tap identifier
The tap name
The tap code
The page number
The number of records per page
The total number of records overall
GET /merchants HTTP/1.1
api_key: 8c54d563-b991-4b76-8a83-557c08166f95
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC123",
"name": "Good Burger",
"description": "Good Burger Main Business Unit",
"is_parent": true,
"schemes": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "MyCompany Scheme",
"code": "MS"
}
],
"tap": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "T123456",
"code": "T123"
}
],
"creatives": [
{
"id": "CA123456789AQWSXZAQWS1236547896541",
"type": "MARKETING",
"width": 2159,
"height": 3075,
"format": "jpg",
"url": "https://assets.crm.com/image/offer.jpg",
"public_id": "crm-com/image",
"srcset": [
{
"width": 200,
"height": 300,
"url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
}
]
}
]
}
],
"paging": {
"page": 2,
"size": 20,
"total": 5124
}
}Request parameters
The name of the entity whose custom fields will be retrieved. If not specified, then all custom field across all entities are returned
Responses
The request has succeeded
Body
Unique key of the custom field
The custom field’s name/label
A description of the custom field
The custom field’s data type
GET /custom_fields?entity_name=ACCOUNTS HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"key": "back_office",
"name": "Back Office",
"description": "The accout's back office code",
"type": "DATE",
"entity": "ACCOUNTS"
}
]