BackOffice Admin

https://sandbox.crm.com/backoffice/v1
Introduction

Welcome to the CRM.COM Application Programming Interface (API) documentation

The CRM.COM API is designed around REST, allowing you to access and extend the software’s current functionality in a simple, programmatic way using intuitive URL endpoints, conventional HTTP requests, response codes, authentication and verbs.

Back-Office API is designed with a main focus on users and external systems that desire to access and extend the functionality found in CRM.COM.

For the Mobile/Web based Applications API please refer to the Self-Service API documentation that provides more details how to allow customer to manage their subscriptions and/or reward accounts.

API Documentation
Unique Resource Identifiers

CRM.COM is built on a domain based micro-service architecture. Our primary resources such as Contact, Account, Wallet, Products, Subscriptions are all created with a unique identifier that uses a performant time based GUID. These are generated when a new resource such as a contact is created. However in some cases external integration may wish to use a unique identfier that is stored in an external system, such as a Bank CIF or Credit Card fingerprint.

Some systems allow from their create APIs to supply a unique identifier as part of the request body. CRM.COM has decided to provide an alternative approach and make an alternative unique identifier available on resources (e.g. on Contacts we provide the contact.code). If such attribute is specified during the create operation it wil be available on subsequent operations as a resource’s identifier, alongside with the GUID that is returned in the response body.

API Reference

CRM.COM API is organized around REST. Our API has specific resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication & verbs.

You can use the entire API in test mode, which does not affect your live data. The API Key used to authenticate any of your requests will determine whether the request is on live mode or test mode.

The API may differ based on each CRM.COM release. For every new release with noticable changes that might alter backwards compatibility, a new version will be created.

Authentication

CRM.COM Back-Office API uses either API Keys to authenticate requests or an authentication JWT token obtained from a user successful logging in.

SECURITY NOTICE

All API requests must be made over HTTPS. Any request made over plain HTTP or without authentication will fail. In addition, API Keys carry many privileges, so be sure to keep them secure! Do not share your secret API Keys in publicly accessible areas, such as GitHub or client-side code.

API KEY AUTHORIZATION HEADER EXAMPLE

curl -X $HTTP_METHOD -H "api_key: 2189341e-981e-9ad5-9912-11101670314a" 

AUTH TOKEN AUTHORIZATION HEADER EXAMPLE

curl -X $HTTP_METHOD -H "authorization: Bearer JWT_TOKEN" 
Requests

API requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Method Usage
POST To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object to the targeted endpoint.
PUT To update the information on an existing object, the PUT method should be used. This will update the specified object if it is found using the provided values, regardless of their current values. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource’s availability prior to issuing an update command, the final state will be the same regardless of its existence. Requests using the PUT method do not need to check the current attributes of the object.
DELETE To remove an existing object from your environment, the DELETE method should be used. Similar to PUT method, the DELETE method is idempotent.
GET For retrieving information about 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.
Responses

Along with the HTTP methods that the API responds to, CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

HTTP Status Description
2XX Return codes in the 200 range indicate that the request was fulfilled successfully and that no error was encountered.
4XX Return codes in the 400 range, typically, indicate that there was an issue with the request that was sent. Most common reasons could be an invalid authentication method, unauthorised requests or the object that you are requesting does not exist.
5XX Return codes in the 500 range indicate that there is a server-side problem and CRM.COM cannot fulfill your request at the moment.

Most of our 4XX range errors that could be handled programmatically contain all the necessary details for a better integration handling. Such details are

  • HTTP Status Code & Error are used for programmatic consumption
  • Message is human-readable and can be used as a default error message
  • Parameters are used for programmatic consumption and can be used for enhancing the interface error message with additional information

4XX ERROR RESPONSE EXAMPLE

An example of a customer not found error is as follows

HTTP/1.1 404 Not Found
    {
        "status": 404,
        "message": "Record not found.",
        "error": "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION",
        "parameters": [
            "contact",
            "789dacae-cf71-414f-9483-ca88acaa46432"
        ]
    }
Response Codes

Below is a list of our common HTTP response codes that can be returned.

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Operations
Accounts

What is an account

POST /contacts/{id}/accounts
PUT /accounts/{id}
GET /contacts/{id}/accounts
POST /accounts/{id}/life_cycle_state
Add Account for Contact
POST /contacts/{id}/accounts

Add a new customer account to an existing contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification_id
string GUID nullable

The account’s classification ID

Example:
4AD9C84FA60F9FE407140E20F707726A
currency_code
string nullable

The account’s currency

Example:
EUR
is_primary
boolean nullable

If set to true, then the account will be set as the primary one even if a different one exists

Example:
true
billing_address_id
string GUID nullable

The unique identification of a contact address which will be set as the billing address of the account. By default, the primary addres (if it exists) will be provided

Example:
E407140E20F707726A4AD9C84FA60F9F

Responses

201 201

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1 

Content-Type: application/json

{
    "classification_id": "4AD9C84FA60F9FE407140E20F707726A",
    "currency_code": "EUR",
    "is_primary": true,
    "billing_address_id": "E407140E20F707726A4AD9C84FA60F9F"
}
Update Account
PUT /accounts/{id}

Update the account of a contact

Path variables

id
string GUID required

The account identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification_id
string GUID

The account’s classification ID

Example:
4AD9C84FA60F9FE407140E20F707726A
is_primary
boolean

If set to true, then the account will be set as the primary one even if a different one exists

Example:
true
billing_address_id
string GUID

The unique identification of a contact address which will be set as the billing address of the account. By default, the primary addres (if exists) will be provided

Example:
4AD9C84FA60F9FE407140E20F707726A
credit_limit
number

Sets the credit limit of the account

Example:
200
payment_terms_id
string

Sets the Account’s Payment Terms.

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://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"
}
List Contact Accounts
GET /contacts/{id}/accounts

Get a list of Contact Accounts. Normally a contact will have a single account but multiple accounts can be used to service different currencies, or different spending profiles.

Path variables

id
string GUID required

The contact identifier whose accounts will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

is_primary
boolean optional

If set to true, then only the primary account of the contact will get retrieved

Example:
true
life_cycle_state
string optional

Retrieve accounts with a specific life cycle state

Pattern: csv
Example:
ACTIVE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
is_primary
boolean

Indicates if this is the primary account of the contact

Example:
true
name
string

The account name

Example:
Default
number
string

The Account number

Example:
AC123456
life_cycle _state
string

The account’s life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
Example:
ACTIVE
currency_code
string

The account’s currency

Example:
EUR
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
balance
number

The account’s calculated balance

Example:
200
credit_limit
number

The account’s credit limit

Example:
100
overdue_amount
number

The unpaid amount that is passed its due date

Example:
50
payment_terms
Object

The account’s Payment Terms

id
string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string
Example:
Net 7
wallet
Object

Wallet related to the Account

id
string

Wallet identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

Wallet code

Example:
9005455565111112
balance
number

Wallet total balance

Example:
9.99
currency_code
string

Currency code

Example:
EUR
life_cycle_state
string

Wallet’s state

Enumeration:
EFFECTIVE
TERMINATED
Example:
EFFECTIVE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/accounts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "is_primary": true,
            "name": "Default",
            "number": "AC123456",
            "life_cycle _state": "ACTIVE",
            "currency_code": "EUR",
            "classification": {
                "id": "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"
            }
        }
    ]
}
Update Account's Life Cycle State
POST /accounts/{id}/life_cycle_state

Change the life cycle state of the Account

Path variables

id
string GUID required

The account identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string required

The life cycle state that the account will changed into

Enumeration:
SUSPENDED
ACTIVE
TERMINATED
Example:
SUSPENDED
transfer_to_account_id
string GUID nullable

The account to which any account balance will get transfered, in case of Termination. Required when terminating the account

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the account

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST 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"
}
Account Financials
GET /accounts/{id}/financials
Get Account Financials
GET /accounts/{id}/financials

Get a single Account with its financial information

Path variables

id
string GUID required

The unique identification of the Account to be retrieved.

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
name
string

The account’s name

Example:
John Smith AC00123456
number
string

The account’s number

Example:
AC00123456
is_primary
boolean

Defines whether the account is the primary one of the contact

Example:
true
life_cycle_state
string

The account’s life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
currency_code
string

The account’s currency (3 code currency)

Example:
EUR
balance
number

The account’s calculated balance

Example:
200
overdue_amount
number

The unpaid amount that is passed its due date

Example:
100.5
credit_limit
number

The account’s credit limit

Example:
98
opening_balance
number

The opening balance brought forwards after the latest closed accounting period

Example:
100.5
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
accounting_period
Object

The latest accounting period for which the account’s opening balance was calculated

id
string

The ID of the latest closed accounting period

name
string

The name of the account’s latest accounting period

Example:
OCTOBER2018
billing_address
Object
id
string GUID

The id of the billing address

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_line_1
string
Example:
2265 Oak Street
address_line_2
string
state_province_county
string
Example:
New York
town_city
string
Example:
Old Forge
postal_code
string
Example:
13420
country_code
string
Example:
USA
payment_terms
Object

The account’s payment terms

id
string

Payment terms identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

Payment terms name

Example:
Net 7
wallet
Object

The account’s related Wallet

id
string

Wallet identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

Wallet code

Example:
9000004434321111
life_cycle_state
string

The wallet life cycle state

Enumeration:
EFFECTIVE
TERMINATED
balance
number

Total balance

Example:
9.99
open_balance
number

Open balance

Example:
5.45
commerce_balance
number

Commerce balance

Example:
4.54
currency_code
string
Example:
EUR
minimum_balance
number

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

Example:
5.99
limits
Array
Object
minimum_amount
number

The minimum amount allowed

Example:
5.99
maximum_amount
number

The maximum amount allowed

Example:
99.99
period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL
Example:
MONTHLY
transaction_type
string

The wallet transaction type for which the limit is applied

Enumeration:
DEBIT
CREDIT
TOPUP
TRANSFER
Example:
CREDIT
auto_topup
Object
threshold
number

Sets the threshold for the auto topup to be performed

Example:
99.99
amount
string

The amount to get topped up

Example:
9.99
payment_method
string

Indicates the method of collecting money

Enumeration:
CARD
WALLET
ACCOUNT_DEBIT
Example:
CARD
payment_method_id
string

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

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
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"
        }
    }
}
Account Rewards
PUT /accounts/{id}/rewards
GET /accounts/{id}/rewards
POST /accounts/{id}/reward_schemes
DELETE /accounts/{id}/reward_schemes/{reward_scheme_id}
POST /accounts/{id}/merchants
DELETE /accounts/{id}/merchants/{merchant_id}
Update Account Rewards
PUT /accounts/{id}/rewards

Update the reward attributes of the primary account of a contact

Path variables

id
string GUID required

The account (identifier) whose reward attributes will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

Only Primary Accounts of a Contact hold Reward information

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
signed_up_on
integer epoch nullable

The date that the customer first signed up

Example:
1583846865
signed_up_organisation_id
string GUID nullable

The organisation identifier that signed up the customer (first time)

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
spending_blocked_status
boolean nullable

Defines whether the spending is blocked for the specific account

Example:
true
automatic_spend_settings
Object nullable

Information about the automatic spend settings for the account

enable_automatic_spend
boolean required

Defines whether automatic spend is enabled for the account

Example:
false
automatic_spend_preference
string nullable

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

Enumeration:
NEXT_MERCHANT_PURCHASE
ALL_MERCHANT_PURCHASE
minimum_wallet_balance
number nullable

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

from_purchase_amount
number nullable

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

Example:
1.76

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/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"
}
Get Account Rewards
GET /accounts/{id}/rewards

Get a single account, along with its reward details

Path variables

id
string GUID required

The account (identifier) which reward details will be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Notes

Only Primary Accounts of a Contact hold Reward information

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The account’s name

Example:
John Smith AC00123456
number
string

The account’s number

Example:
AC00123456
currency_code
string

The account’s currency (3 code currency)

Example:
EUR
sign_up_on
integer epoch

The date when the account was signed up for the first time

Example:
1583846865
sign_up_organisation
Object

Information about the organisation that sign up the account for the first time

id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
CRMdotCOM
spending_blocked_status
boolean

Defines whether the account can spend or not

Example:
false
spending_blocked_date
integer epoch

The date that the spending status of the account was updated

Example:
1583846865
spending_blocked_user
Object

Information about the user that updated the spending status of the account

id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
email_address
string

The user’s email address

Example:
johndoe@crm.com
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
automatic_spend_settings
Object

Information about the automatic spend settings for the account

enable_automatic_spend
boolean

Defines whether automatic spend is enabled for the account

Example:
true
automatic_spend_preference
string

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

Enumeration:
NEXT_MERCHANT_PURCHASE
ALL_MERCHANT_PURCHASE
minimum_wallet_balance
number

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

Example:
0.52
from_purchase_amount
number

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

Example:
1.78
merchants
Array

Information about the merchants that automatic spending is allowed (Deprecated, replaced by Organisations)

Object
id
string GUID

The merchant record identifier

Example:
REC1E31269B76D7A65ACCE45B2E68DFD
is_next_visit
boolean

Defines whether the merchant is setup for automatic spend on the next visit

Example:
false
organisation
Object

Information about organisation

id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Bravo Coffee
reward_tier
Object

Information about the account’s reward tier

id
string GUID

The reward tier identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward tier name

Example:
Gold
color
string

The designated hexadecimal code of the tier’s color

Example:
#d4af37
period_value_units
number

The account’s value units that accumulated during the last rolling period

Example:
222
lifetime_value_units
number

The account’s value units that accumulated overall

Example:
333
tier_progression
Array

Details about The progression percentage for each reward tier

Object
percentage
number

The progression percentage until the reward tier

Example:
45.98
tier
Object

Details about the reward tier

id
string GUID

The reward tier identifier

Example:
41ed2390-4058-81a2-d41b-18acaea22c84
name
string

The reward tier name

Example:
Gold
value_units
integer

The tier (threshold) value units (inclusive)

Example:
2500
remaining_value_units
integer

The remaining value units to reach this tier

Example:
123
joined_reward_schemes
Array

Information about the reward schemes that the account has signed up to

Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward scheme name

Example:
CRMdotCOM Scheme
signed_up_on
integer epoch

The date when the account was signed up on the specific reward scheme

Example:
1583846865
email_address
string

The email address that was used during sign up (applicable if the reward scheme is a close loop scheme based on email domains)

Example:
johndoe@crm.com
sign_up_option
string

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP
SELF_SIGN_UP
CLOSE_LOOP_SIGN_UP
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/accounts/41dc3d8a-5ab2-3dc8-83d5-33501eb1949f/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
    }
}
Sign up to a Reward Scheme
POST /accounts/{id}/reward_schemes

Sign up the account to a specific reward scheme

Path variables

id
string GUID required

The account (identifier) that will be signed up to the reward scheme

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
reward_scheme_id
string GUID required

The reward scheme that the account has signed up

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
email_address
string nullable

The email address of the customer requestng to sign uo to a reward scheme based on supported domains

Example:
johndoe@crm.com
sign_up_code
string nullable

The code that will verify that the customer is allowed to sign up to a close loop reward scheme

Example:
ABCDEFG1234
sign_up_date
integer epoch nullable

The date that the account has signed up (if not specified, defaults to current date)

Example:
1589796854

Responses

200 200

OK

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DXD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/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"
}
Sign out from a Reward Scheme
DELETE /accounts/{id}/reward_schemes/{reward_scheme_id}

Sign out the account from a specific reward scheme

Path variables

id
string GUID required

The account (identifier) that will be signed off from the reward scheme

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
reward_scheme_id
string GUID required

The reward scheme (identifier) that the account has signed off

Example:
CAD1E31269B76D7A65ACCE45B2E68DXD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DXD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Add Merchants
POST /accounts/{id}/merchants

Add a set of new merchants for automatic spends for that account

Path variables

id
string GUID required

The account (identifier) whose merchant preferencees will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
merchants
Array required

Defines a list of merchants that are authorised to perform automatic awards spending for that account

Unique items: YES
Object
organisation_id
string GUID required

The organisation identifier that should be authorised to perform automatic awards spending

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
is_next_visit
boolean nullable

Defines whether the merchant is setup for automatic spend on the next visit

Example:
false

Responses

200 200

OK

Body
Object
merchants
Array

A list of merchants that are authorised to perform automatic awards spending for that account

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://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"
        }
    ]
}
Remove Merchant
DELETE /accounts/{id}/merchants/{merchant_id}

Remove an exisintg merchant from an account’s automatic spend preferences

Path variables

id
string GUID required

The account (identifier) whose reward attributes will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
merchant_id
string GUID required

The merchant (identifier) that will be removed from the spend preferences

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/accounts/CAD1E31269B76D7A65ACCE45B2E68DFD/merchants/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Account Wallets
POST /accounts/{id}/wallets
Add Wallet for Account
POST /accounts/{id}/wallets

Adds 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

id
string required

Account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request body

Object
minimum_balance
integer

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

Example:
10.99
limit_rules
Array

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

Object
limit_amount
integer

The maximum amount allowed

Example:
100.99
transaction_type
string

The wallet transaction type for which the limit is applied

Enumeration:
DEBIT
CREDIT
Example:
DEBIT
period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL
Example:
MONTHLY

Responses

201 Created
Body
Object
id
string

The Wallet identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
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"
}
Wallets
PUT /wallets/{id}
POST /wallets/{id}/actions
GET /wallets/{id}/commerce_balances
POST /journals
Update Wallet
PUT /wallets/{id}

Updates a single Wallet.

Path variables

id
string required

The unique identifier of the Wallet to be updated

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
auto_topup
Object

Wallet’s auto top up settings.

threshold
number

The wallet’s minimim balance threshold that triggers this rules once it is reached

Example:
0.01
amount
number

The auto top up’s amount

Example:
10.5
payment_method
Object

The payment method from which funds will be automatically retrieved

type
string
Enumeration:
CARD
WALLET
ACCOUNT_DEBIT
Example:
CARD
id
string

The contact’s payment method identifier.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
termed_topup
Object
amount
number
Example:
10.5
frequency
Object
period
string
Example:
MONTHS
value
integer
Example:
1
topup_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
MONDAY
payment_method
Object
type
string
id
string
limit_rules
Array
Object
name
string
Example:
VIP
maximum_amount
number
Example:
9.99
maximum_number
integer
Example:
10
period
string
Example:
ANNUAL
transaction_type
Array
Example:
["TOPUP"]
string
Example:
TOPUP

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated Wallet

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://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"
}
Actions on Wallet
POST /wallets/{id}/actions

Updates an existing Wallet’s state

Path variables

id
string required

Wallet identifier

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

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
action
string

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

Enumeration:
EFFECTIVE
TERMINATED
Example:
TERMINATED

Responses

201 Created
Body
Object
id
string

The updated wallet’s identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://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"
}
List Wallet Commerce Balances
GET /wallets/{id}/commerce_balances

Retrieves 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

id
string GUID required

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

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

Request parameters

spend_condition_id
string GUID optional

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

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

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

Example:
true
currency_code
string optional

If not specified, then the balance breakdown of the wallet’s primary currency will be returned by default.

Example:
EUR
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Array
Object
id
string GUID

The spend condition group identifier

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

The name of the spend condition group

Example:
Happy Hour
amount
number

The amount that is allocated to the specified spend condition

Example:
100.5
curency_code
string
organisations
Array

The organisations where the amount can be spent at

Object
id
string GUID

The organsiation identifier

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

The name of the organisation

Example:
Cafe
locations
Array

The location of the organisation

Object

Information about the organisation’s location

name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
products
Array

The products that the amount can be spent for

Object
id_type
string

The type of the ID to be provided

Enumeration:
PRODUCT
FAMILY
TYPE
BRAND
CATEGORY
id
string GUID

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

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

The name of the product

Example:
Coffee
description
string

The descrtipion of the product

Example:
Brazilian Coffee
timings
Array

The time when the amount can be spent

Object
month
integer

The month as a condition (1-12)

Example:
1
day
integer

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

Example:
1
start_time
string

The start time of the day in 24 Hour format

Example:
19:00
end_time
string

The end time of the day in 24 Hour format

Example:
21:00
expiration
Object

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

zero_to_thirty
number

The amount that will expire in up to 30 days

Example:
50.5
thirty_to_sixty
number

The amount that will expire from 30 to 60 days

Example:
50.5
sixty_to_ninety
number

The amount that will expire from 60 to 90 days

Example:
50.5
ninety_plus
number

The amount that will expire in more than 90 days

Example:
50.5
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/wallets/234fbc54-bc32-1990-ce59-76c45e6377a8/commerce_balances HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "234fbc54-bc32-1990-ce59-76c45e6377a8",
        "name": "Happy Hour",
        "amount": 100.5,
        "curency_code": "",
        "organisations": [
            {
                "id": "234fbc54-bc32-1990-ce59-76c45e6377a8",
                "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,
                        "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
                    }
                ]
            }
        ],
        "products": [
            {
                "id_type": "BRAND",
                "id": "234fbc54-bc32-1990-ce59-76c45e6377a8",
                "name": "Coffee",
                "description": "Brazilian Coffee"
            }
        ],
        "timings": [
            {
                "month": 1,
                "day": 1,
                "start_time": "19:00",
                "end_time": "21:00"
            }
        ],
        "expiration": {
            "zero_to_thirty": 50.5,
            "thirty_to_sixty": 50.5,
            "sixty_to_ninety": 50.5,
            "ninety_plus": 50.5
        }
    }
]
Create Wallet Journal
POST /journals

Creates a Wallet Journal Entry that either debits or credits the wallet. A single journal entry is created per Web API call.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
wallet_id
string GUID required

The unique identifier for which the journal entry will be created

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

The amount of the journal

Example:
10
currency_code
string

If not specified, then the wallet’s primary currency is used to log the journal entry

Example:
EUR
description
string

The description of the journal

Example:
Credit adjustment by 10 EUR
type
string required

The type of the journal

Enumeration:
CREDIT
DEBIT
Example:
CREDIT
spend_condition_id
string GUID

The unique identifier of the related spend condition. If specified, then the journal entry’s amount is move to the wallet’s business balance

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

The valid from date

Example:
1587988965
valid_to
integer epoch

The valid to date

Example:
1587988965
created_on
integer epoch

The date and time when the journal actually created

Example:
1588081851
allow_below_zero
boolean

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

Example:
true

Responses

200 200

OK

Body
Object
id
string GUID

The wallet journal identifier

Example:
234fbc54-bc32-1990-ce59-76c45e6377a8
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/journals HTTP/1.1 

Content-Type: application/json

{
    "wallet_id": "4AD9C84FA60F9FE407140E20F707726A",
    "amount": 10,
    "type": "DEBIT",
    "description": "Credit adjustment by 10 EUR",
    "spend_condition_id": "4AD9C84FA60F9FE407140E20F707726A",
    "valid_from": 1587988965,
    "valid_to": 1587988965,
    "created_on": 1588081851
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Activities
POST /activities
PUT /activities/{id}
DELETE /activities/{id}
PUT /activities/{id}/status
GET /activities
GET /activities/{id}
Create Activity
POST /activities

Create a new activity

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The activity name

Example:
Call customer
description
string nullable

The activity description

Example:
We need to call the customer (after 4pm) in order to schedule a demo
type_id
string GUID required

The GUID of the activity type.

Example:
CEEE83D6E0804A30966F684B0269AD91
date
integer epoch

The date of the activity.

Example:
8634785
from_time
string

The date and time that is scheduled for the activity to take place

Example:
09:00
to_time
string

The date and time that is scheduled for the activity to be completed.

Example:
09:30
address_id
string nullable

The id of the address associated with the contact. Either the address_id or the use_entity_address can be specified, not both

Example:
JHGDSYGSDY656GFHGF
use_entity_address
boolean

Use the entity address as the Activity address. In cases where an Activity is being created for an entity which has an address (e.g. Contact, Order, Service Request) then use that address as the default Activity address. Either the address_id or the use_entity_address can be specified, not both

Example:
false
linked_to
Array

Related linked entity details.

Object
type
string

The type of related entity.

Enumeration:
CONTACT
LEAD
SERVICE_REQUEST
ORDER
id
string

The related entity identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
assign_to
Object nullable
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The activity identifier that was created

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/activities HTTP/1.1 

Content-Type: application/json

{
    "name": "Call customer",
    "description": "We need to call the customer (after 4pm) in order to schedule a demo",
    "type_id": "CEEE83D6E0804A30966F684B0269AD91",
    "date": 8634785,
    "from_time": "09:00",
    "to_time": "09:30",
    "address_id": "JHGDSYGSDY656GFHGF",
    "use_entity_address": "false",
    "linked_to": [
        {
            "type": "ORDER",
            "id": "CEEE83D6E0804A30966F684B0269AD91"
        }
    ],
    "user_id": "CEEE83D6E0804A30966F684B0269USER",
    "assign_to": {
        "user_id": "1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf",
        "team_id": "a43f08ca-998b-afbc-6ed4-c9dc2d136935"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Update Activity
PUT /activities/{id}

Update an existing activity

Path variables

id
string GUID required

The activity identifier that will be updated

Example:
QWERTY1234543212345678UJIKY76HJR

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The activity name

Example:
Approve Offers
description
string nullable

The activity description

Example:
Require 4 approvals for an offer
address_id
string

The address id associated to the contact and the activity

Example:
GNEHDFHDBFDFFDSD
date
integer epoch

The date that the activity is scheduled.

Example:
863478
from_time
string

The start time of the scheduled activity.

Example:
09:00
to_time
string

The end time of the scheduled activity.

Example:
09:30
linked_to
Array

Related linked entity details.

Object
type
string

The type of the related entity

Enumeration:
CONTACT
LEAD
SERVICE_REQUEST
ORDER
id
string

The related entity identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
assign_to
Object
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The activity identifier that was updated

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/activities/QWERTY1234543212345678UJIKY76HJR HTTP/1.1 

Content-Type: application/json

{
    "name": "Approve Offers",
    "description": "Require 4 approvals for an offer",
    "address_id": "GNEHDFHDBFDFFDSD",
    "date": 863478,
    "from_time": "09:00",
    "to_time": "09:30",
    "linked_to": [
        {
            "type": "ORDER",
            "id": "CEEE83D6E0804A30966F684B0269AD91"
        }
    ],
    "user_id": "CEEE83D6E0804A30966F684B0269USER",
    "assign_to": {
        "user_id": "1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf",
        "team_id": "a43f08ca-998b-afbc-6ed4-c9dc2d136935"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Delete Activity
DELETE /activities/{id}

Delete an existing activity

Path variables

id
string GUID required

The activity identifier that will be deleted

Example:
QWERTY1234543212345678UJIKY76HJR

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/automations/QWERTY1234543212345678UJIKY76HJR HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Change Activity State
PUT /activities/{id}/status

Update an existing activity’s status

Path variables

id
string GUID required

The activity identifier whose life cycle state will be updated

Example:
QWERTY1234543212345678UJIKY76HJR

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
status
string required

Defines the new life cycle state of the activity

Enumeration:
PENDING

The activity will be created with this status.

COMPLETED

The activity will be closed with this status.

CANCELLED

The activity will be cancelled with this status.

Responses

200 200

Successful Request

Body
Object
id
string GUID

The activity identifier that was updated

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/activities/QWERTY1234543212345678UJIKY76HJR/status HTTP/1.1 

Content-Type: application/json

{
    "status": "CANCELLED"
}
List Activities
GET /activities

Search for activities

Request parameters

order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
contact_id
string GUID optional

Filter based on the related Order

Example:
c0a0c2bf-55fa-4a22-b151-a8660c3877b1
order_id
string optional
lead_id
string GUID optional

Filter based on the related Lead

Example:
c0a0c2bf-55fa-4a22-b151-a8660c3877b1
service_request_id
string GUID optional

Filter based on the related Service Request

Example:
c0a0c2bf-55fa-4a22-b151-a8660c3877b1
type_id
string optional

The id of the activity type

Example:
HJGDJSHFSDHGFu77566HFVDHGSF
search_value
string optional

Search for an activity based on name

Example:
installation job
created_on
string optional

Filter based on the created date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. created_on[gte]=1618395497&created_on[lt]=1618395497).

Enumeration:
created_on[gt]

Returns results where the created date is greater than this value

created_on[gte]

Returns results where the created date is greater than or equal to this value

created_on[lt]

Returns results where the created date is less than this value

created_on[lte]

Returns results where the created date is less then or equal to this value

statuses
array of string optional

Details pertaining to the statuses of the activities.

Collection format: csv
tag_ids
array of string optional

The id’s of the tags to filter by

Collection format: csv
user_id
string GUID optional

Filter based on the User who is responsible to complete it

Example:
c0a0c2bf-55fa-4a22-b151-a8660c3877b1
assign_to_user_id
string GUID optional

Filters based on specific assign to user

Example:
c45903ff-4a00-49bd-93b4-6b2f0373ce20
assign_to_team_id
string GUID optional

Filters based on specific assign to team

Example:
5beb415c-3246-1a10-f806-3f975e4898dc
include_custom_fields
boolean optional

Retrieve custom fields?

Default:
true
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value,key;value

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The activity identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The activity name

Example:
Call customer
description
string

The activity description

Example:
We need to call the customer to arrange a demo
status
string

The activity life cycle state

Enumeration:
PENDING
COMPLETED
date
integer epoch

The date of the scheduled activity

Example:
198735487
from_time
string

The time from when the activity is scheduled.

Example:
09:00
to_time
string

The time that the activity is scheduled to finish.

Example:
09:30
activity_type
Object

The activity type

id
string

The id of the activity type

Example:
JKHGFSD878JHGDHJGD
name
string

The name of the activity type

Example:
site visit
colour
string

The colour code of the activity type

Example:
7GH86H7
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
lead
Object

The details of the lead

id
string GUID

The lead identifier

Example:
AJBGJHFGKSF78676JHGS56
title
string

The name of the lead

Example:
ASOS
service_request
Object

The service request ticket number

id
string GUID

The service request unique identifier

Example:
AJBGJHFGKSF78676JHGS56
number
string

The ticket number of the service request

Example:
SR10001
order
Object

The order that the activity was created through

id
string

The order id

Example:
JGDAKJHDAKJHAJK87897
number
string

The order number

Example:
O101367
assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/activities HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "name": "Call customer",
            "number": "ACT1001",
            "description": "We need to call the customer to arrange a demo",
            "status": "COMPLETED",
            "date": 198735487,
            "from_time": "09:00",
            "to_time": "09:30",
            "activity_type": {
                "id": "JKHGFSD878JHGDHJGD",
                "name": "site visit",
                "colour": "7GH86H7"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "lead": {
                "id": "AJBGJHFGKSF78676JHGS56",
                "title": "ASOS"
            },
            "service_request": {
                "id": "AJBGJHFGKSF78676JHGS56",
                "number": "SR10001"
            },
            "order": {
                "id": "JGDAKJHDAKJHAJK87897",
                "number": "O101367"
            },
            "user": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "John Doe"
            },
            "assign_to": {
                "user": {
                    "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
                    "name": "John Doe",
                    "username": "j_doe@crm.com"
                },
                "team": {
                    "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
                    "name": "Support"
                }
            },
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Activity
GET /activities/{id}

Get details for a specific activity

Path variables

id
string GUID required

The activity identifier that will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The activity identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The activity name

Example:
Call customer
description
string

The activity description

Example:
Arrange a call with the customer after 4pm to schedule a demo for next week
date
integer epoch

The date and time that the activity is scheduled for

Example:
7675675
from_time
string

The time that the activity is scheduled to start.

Example:
09:00
to_time
string

The time that the activity is scheduled to be completed.

Example:
09:30
created_date
integer epoch

The date the activity was created.

type
Object

The type of activity

id
string

The id of the type

Example:
HGJDHGSJDHG
name
string

the name of the type

Example:
site visit
color
string

the colour of the type.

Example:
876FD5
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
service_request
Object

The details of the sercice request

id
string GUID

The id of the service request

Example:
JHGHGF7576HGFTGD564654
number
string

The ticket number of the service request

Example:
SRV78001
lead
Object

The details of the lead

id
string

The id of the lead

Example:
JHGSD6576JKDGSFKJG
title
string

The name of the lead

Example:
ASOS
order
Object
id
string

The order ID

Example:
JGKDJSHSHDKAJHAKJD
number
string

The order number

Example:
O10306P
address
Object

The address of the activity

address_line_1
string
Example:
Elia Papakyriakou
address_line_2
string
Example:
7 Tower Stars
state_province_county
string
Example:
Egkomi
town_city
string
Example:
Nicosia
postal_code
string
Example:
2000
country
string
Example:
CY
lat
string
Example:
523654.098795
lon
string
Example:
880932.981221
googleplaceid
string
Example:
ad23rewf4472vnm90001
statuses
Array

The life cycle states of the activity

Object
status
string
Enumeration:
PENDING
COMPLETED
CANCELLED
date
string date

The date that the activity enetered that stated

assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/activities/CEEE83D6E0804A30966F684B0269AD91 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "name": "Call customer",
    "number": "ACT1001",
    "description": "Arrange a call with the customer after 4pm to schedule a demo for next week",
    "date": 7675675,
    "from_time": "09:00",
    "to_time": "09:30",
    "created_date": 1,
    "type": {
        "id": "HGJDHGSJDHG",
        "name": "site visit",
        "color": "876FD5"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "service_request": {
        "id": "JHGHGF7576HGFTGD564654",
        "number": "SRV78001"
    },
    "lead": {
        "id": "JHGSD6576JKDGSFKJG",
        "title": "ASOS"
    },
    "order": {
        "id": "JGKDJSHSHDKAJHAKJD",
        "number": "O10306P"
    },
    "address": {
        "address_line_1": "Elia Papakyriakou",
        "address_line_2": "7 Tower Stars",
        "state_province_county": "Egkomi",
        "town_city": "Nicosia",
        "postal_code": "2000",
        "country": "CY",
        "lat": "523654.098795",
        "lon": "880932.981221",
        "googleplaceid": "ad23rewf4472vnm90001"
    },
    "statuses": [
        {
            "status": "PENDING",
            "date": ""
        }
    ],
    "user": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "John Doe"
    },
    "assign_to": {
        "user": {
            "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
            "name": "John Doe",
            "username": "j_doe@crm.com"
        },
        "team": {
            "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
            "name": "Support"
        }
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Activity Tags

The following functionality relates to tags for activities

POST /activities/{id}/tags
PUT /activities/{id}/tags
DELETE /activities/{id}/tags/{tag_id}
GET /activities/{id}/tags
Add Activity Tags
POST /activities/{id}/tags

The following process adds tags to an activity

Path variables

id
string GUID required

The activity GUID

Example:
HRDGSWRSFVSDSDBSDSSDDE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string GUID

The tag id

Example:
FDHNFDBR675765ghdh
Example 1
POST https://sandbox.crm.com/backoffice/v1/activities/HRDGSWRSFVSDSDBSDSSDDE/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "FDHNFDBR675765ghdh"
        }
    ]
}
Update Activity Tags
PUT /activities/{id}/tags

The following process updates tags for an activity

Path variables

id
string GUID required

The activity GUID

Example:
JGSDGJKAJKGDAKJGS

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string GUID

The tag id

Example:
JGFJHGJHSDGHJSG
Example 1
PUT https://sandbox.crm.com/backoffice/v1/activities/JGSDGJKAJKGDAKJGS/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "JGFJHGJHSDGHJSG"
        }
    ]
}
Delete Activity Tag
DELETE /activities/{id}/tags/{tag_id}

Deletes a tag on a activity.

Path variables

id
string GUID required

The id of the activity.

Example:
ef9a1f84-2d4b-c9eb-afc7-a142e202a9ef
tag_id
string GUID required

The id of the tag

Example:
KJDFHKJGFSJHG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/activities/ef9a1f84-2d4b-c9eb-afc7-a142e202a9ef/tags/KJDFHKJGFSJHG HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Get Activity Tags
GET /activities/{id}/tags

The following process retrieves the tags for a activity

Path variables

id
string GUID required

The id of the activity.

Example:
JHGSDJHGAHJGD

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

the tag ID

Example:
JKGJHFSDJHGDSJHGA
name
string

Name of Tag

Example:
Maintenance
colour
string

Colour of tag

Example:
The colour of the tag
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/activities/JHGSDJHGAHJGD/tags HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JKGJHFSDJHGDSJHGA",
            "name": "Maintenance",
            "colour": "The colour of the tag"
        }
    ]
}
Analytics
GET /organisations/{id}/analytics
GET /contacts/{id}/analytics
Insights
POST /insights
PUT /insights/{id}
DELETE /insights/{id}/
GET /insights
GET /insights/{id}
POST /insights/{id}/events
POST /insights/{id}/filters
POST /insights/{id}/breakdowns
GET /insights/{id}/results
POST /insights/{id}/preview
POST /insights/{id}/exports
Create Insight
POST /insights

Create a new insight

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The insight name

Example:
Marketing customers
description
string nullable

The insight description

Example:
A list of customers that own an account

Responses

200 OK
Body
Object
id
string GUID

The insight identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Marketing customers",
    "description": "A list of customers that own an account"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05"
}
Update Insights
PUT /insights/{id}

Updates the basic information of an insight

Path variables

id
string GUID required

The insight identifier that will be updated

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The insight name

Example:
Rewards Award
description
string nullable

The insight’s description

Example:
List of contacts owning a non-terminated account
refresh_frequency
integer
Example:
1

Responses

200 200
Body
Object
id
string GUID

The insight identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/insights/c0d4712e-6688-4604-b3d6-d084e4d2dc05 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Rewards Award",
    "description": "List of contacts owning a non-terminated account",
    "refresh_frequency": 1
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05"
}
Delete Insights
DELETE /insights/{id}/

Delete an existing insight

Path variables

id
string GUID required

The insight identifier that will be deleted

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/insights/c0d4712e-6688-4604-b3d6-d084e4d2dc05/ HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Insights
GET /insights

Returns a list of insights

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200
Body
Object
content
Array
Object
id
string GUID

The insights unique identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The insight’s name

Example:
Marketing customers
descripion
string

The insights’s description

Example:
List customers owning an account
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/insights HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Marketing customers",
            "descripion": "List customers owning an account"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Insight
GET /insights/{id}

Get all data for a single insight

Path variables

id
string GUID required

The insight identifier that will be retrieved

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The insight identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
name
string

The insight name

Example:
Rewards Award
events
Array
Object
id
string GUID

The event identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
name
string
Example:
Purchases
event_name
string
Example:
SPEND
totals
Object
is_frequency
boolean
property_name
string
Example:
amount
criteria
Array
Object
name
string
Example:
A
property
Object
property
string
Example:
venue.name
operator
string
Example:
IS
value_list
Array
Example:
["Costa Coffee Nicosia"]
string
Example:
Costa Coffee Nicosia
filters
Array
Object
id
string GUID

The filter identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
name
string
type
string
Example:
CONTACT
property_name
string
operator
string
Example:
NOT_EQUAL
min_value
string
max_value
string
value_list
Array of string
breakdowns
Array
Object
id
string GUID

The breakdown identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
name
string

simple naming A, B, C used for ordering

type
string
Example:
CONTACT
property_name
string
Example:
city
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/insights/c0d4712e-6688-4604-b3d6-d084e4d2dc05 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05",
    "name": "Rewards Award",
    "events": [
        {
            "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05",
            "name": "Purchases",
            "event_name": "SPEND",
            "totals": {
                "is_frequency": true,
                "property_name": "amount"
            },
            "criteria": [
                {
                    "name": "A",
                    "property": {
                        "property": "venue.name",
                        "operator": "IS",
                        "value_list": [
                            "Costa Coffee Nicosia"
                        ]
                    }
                }
            ]
        }
    ],
    "filters": [
        {
            "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05",
            "name": "",
            "type": "CONTACT",
            "property_name": "",
            "operator": "NOT_EQUAL",
            "min_value": "",
            "max_value": "",
            "value_list": [
                ""
            ]
        }
    ],
    "breakdowns": [
        {
            "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05",
            "name": "",
            "type": "CONTACT",
            "property_name": "city"
        }
    ]
}
Add Insight Events
POST /insights/{id}/events

Adds a set of events on an insight

Path variables

id
string required

Request body

Object
events
Array
Object
name
string required
Example:
Purchases
event_name
string
Enumeration:
PURCHASE
AWARD
SPEND
totals
Object
is_frequency
boolean

if the measurement is Freqency or Total of property

property_name
string

Name of the property to sum for a total or count frequency

criteria
Array
Object
name
string
Example:
A
property
Object
property
string
Example:
venue.name
operator
string

List of selection operators

Enumeration:
IS
IS_NOT
CONTAINS
DOES_NOT_CONTAIN
value_list
Array of string

List of values if the operator is contains or single item if matching

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights/{id}/events HTTP/1.1 

Content-Type: application/json

{
    "events": [
        {
            "name": "Purchases",
            "event_name": "SPEND",
            "totals": {
                "is_frequency": false,
                "property_name": "amount"
            },
            "criteria": [
                {
                    "name": "A",
                    "property": {
                        "property": "venue.name",
                        "operator": "IS",
                        "value_list": [
                            "Costa Coffee Nicosia"
                        ]
                    }
                }
            ]
        }
    ]
}
Add Insight Filters
POST /insights/{id}/filters

Adds a set of filters on an insight

Path variables

id
string required

Request body

Object
filters
Array
Object
name
string
type
string
Enumeration:
EVENT
CONTACT
property_name
string
operator
string

Use Operator

Enumeration:
IS
IS_NOT
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
EQUAL
NOT_EQUAL
min_value
string
max_value
string
value_list
Array of string
Example:
Venue1,Venue2

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights/{id}/filters HTTP/1.1 

Content-Type: application/json

{
    "filters": [
        {
            "name": "",
            "type": "EVENT",
            "property_name": "",
            "operator": "IS_NOT",
            "min_value": "",
            "max_value": "",
            "value_list": [
                ""
            ]
        }
    ]
}

HTTP/1.1 201 Created 
Add Insight Breakdowns
POST /insights/{id}/breakdowns

Adds a set of breakdowns on an insight

Path variables

id
string GUID required

The insight identifier which breakdown will be set

Example:
96578cce-9a50-575e-ed6a-46ae13c9219f

Request body

Object
breakdowns
Array
Object
name
string
type
string
Enumeration:
EVENT
CONTACT
property_name
string

name of the property to create the breakdown

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights/{id}/breakdowns HTTP/1.1 

Content-Type: application/json

{
    "breakdowns": [
        {
            "name": "",
            "type": "CONTACT",
            "property_name": ""
        }
    ]
}

HTTP/1.1 201 Created 
Get Insight Results
GET /insights/{id}/results

Retrieve results of a specific insight

Path variables

id
string GUID required

The insight identifier which results will be retrieved

Example:
04f28639-5ceb-a25e-1e44-b1109e533f42

Request parameters

start_date
integer epoch optional

The start date of the insight sequence

Example:
1612953199
end_date
integer epoch optional

The end date of the insight sequence

Example:
1612953199

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
breakdown
Object
id
string GUID

A temporary identifier to link child levels

Example:
bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f
parent_id
string GUID

The identifier of the previous level

Example:
bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f
level
integer

The breakdown level 0 = EVENTS

Example:
1
property_name
string

The name of the property within the group

Example:
venue.name
property_value
string

The value of the property

Example:
Costa Coffee Larnaca
event_name
string

The name of the event

count
integer

The number of points can be used for frequency

Example:
1
amount
number

The decimal amounts for the level

Example:
12.8
list_name
string

Applicable only if the property is a list and represents the list name

Example:
products
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/insights/04f28639-5ceb-a25e-1e44-b1109e533f42/results HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "breakdown": {
                "id": "bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f",
                "parent_id": "bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f",
                "level": 1,
                "property_name": "venue.name",
                "property_value": "Costa Coffee Larnaca",
                "event_name": "",
                "count": 1,
                "amount": 12.8,
                "list_name": "products"
            }
        }
    ]
}
Preview Insight Results
POST /insights/{id}/preview

Preview the results of a specific insight

Path variables

id
string GUID required

The insight identifier which results will be previewed

Example:
62cb9ada-3a7b-cafb-b7a7-7c103011fa48

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
start_date
integer epoch required

The start date of the insight sequence

Example:
1612953199
end_date
integer epoch required

The end date of the insight sequence

Example:
1612953199
events
Array
Object
name
string required
Example:
Purchases
event_name
string
Enumeration:
PURCHASE
AWARD
SPEND
totals
Object
is_frequency
boolean

if the measurement is Freqency or Total of property

property_name
string

Name of the property to sum for a total or count frequency

criteria
Array
Object
name
string
Example:
A
property
Object
property
string
Example:
venue.name
operator
string

List of selection operators

Enumeration:
IS
IS_NOT
CONTAINS
DOES_NOT_CONTAIN
value_list
Array of string

List of values if the operator is contains or single item if matching

filters
Array
Object
name
string
type
string
Enumeration:
EVENT
CONTACT
property_name
string
operator
string

Use Operator

Enumeration:
IS
IS_NOT
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
EQUAL
NOT_EQUAL
min_value
string
max_value
string
value_list
Array of string
Example:
Venue1,Venue2
breakdowns
Array
Object
name
string
type
string
Enumeration:
EVENT
CONTACT
property_name
string

name of the property to create the breakdown

Responses

200 OK
Body
Object
content
Array
Object
breakdown
Object
id
string GUID

A temporary identifier to link child levels

Example:
bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f
parent_id
string GUID

The identifier of the previous level

Example:
bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f
level
integer

The breakdown level 0 = EVENTS

Example:
1
property_name
string

The name of the property within the group

Example:
venue.name
property_value
string

The value of the property

Example:
Costa Coffee Larnaca
event_name
string

The name of the event

count
integer

The number of points can be used for frequency

Example:
1
amount
number

The decimal amounts for the level

Example:
12.8
list_name
string

Applicable only if the property is a list and represents the list name

Example:
products
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights/62cb9ada-3a7b-cafb-b7a7-7c103011fa48/preview HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "start_date": 1612953199,
    "end_date": 1612953199,
    "events": [
        {
            "name": "Purchases",
            "event_name": "PURCHASE",
            "totals": {
                "is_frequency": true,
                "property_name": ""
            },
            "criteria": [
                {
                    "name": "A",
                    "property": {
                        "property": "venue.name",
                        "operator": "IS_NOT",
                        "value_list": [
                            ""
                        ]
                    }
                }
            ]
        }
    ],
    "filters": [
        {
            "name": "",
            "type": "CONTACT",
            "property_name": "",
            "operator": "DOES_NOT_CONTAIN",
            "min_value": "",
            "max_value": "",
            "value_list": [
                ""
            ]
        }
    ],
    "breakdowns": [
        {
            "name": "",
            "type": "CONTACT",
            "property_name": ""
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "breakdown": {
                "id": "bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f",
                "parent_id": "bb686ff0-e7a4-a8a6-05a6-cfe8e39f675f",
                "level": 1,
                "property_name": "venue.name",
                "property_value": "Costa Coffee Larnaca",
                "event_name": "",
                "count": 1,
                "amount": 12.8,
                "list_name": "products"
            }
        }
    ]
}
Get Distinct Values for an Insight property
GET /distincts

Get a list of distinct values for a contact or event property

Request parameters

collection
string optional

Contact or Event collectioons

Example:
CONTACT, EVENT
property_name
string optional

city

Responses

200 OK
Body
Array
Object
property_value
string

Value of the property

Example:
London
Example 1
GET https://sandbox.crm.com/backoffice/v1/distincts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "property_value": "London"
    }
]
Export Insight Results
POST /insights/{id}/exports

Export the results of a specific insight

Path variables

id
string GUID required

The insights (identifier) that will be exported

Example:
efc5c8af-56ba-3d6f-d180-18be6dd04cc8

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
type
string required

Defines what data should be exported from the related insight results

Enumeration:
RESULTS

Export results in a tabular format, excluding underlying data

UGD

Export all underlying granular data that were used for this Insight

format
string nullable

Defines the file format in which the exported data should be exported

Enumeration:
csv

CSV file

Default:
csv

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/insights/efc5c8af-56ba-3d6f-d180-18be6dd04cc8/exports HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "type": "UGD",
    "format": "csv"
}

HTTP/1.1 200 OK 
Reports
POST /reports/{name}/preview
POST /reports/{name}
PUT /reports/{id}
DELETE /reports/{id}
GET /reports/{id}
Preview Report
POST /reports/{name}/preview

Runs the report in preview mode, i.e. a subset of the report’s results are returned for preview purposes (max 10 records included in the response)

Path variables

name
string required

The report (unique name) that will be previewed

Enumeration:
contacts_summary
contacts_orders_analysis
order_details
contacts_rewards_analysis
organisations_rewards_analysis
organisations_rewards_statement
reward_offer_performance
devices_summary
subscriptions_summary
service_requests_summary
service_requests_analysis

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
filters_set
Array required

Set of filters based on which the report runs

Object
key
string required

The filter’s name

Example:
period_from
value
string required

The filter’s value as this was specified by the user

Example:
This month
columns_set
Array required

Set of columns that will be included in the report’s preview. Up to 10 columns are included by default

Example:
Number, Name
Object
key
string

The field’s name

Example:
product_code

Responses

200 OK
Body
Object
content
Array
Object
fields
Array
Object
key
string
Example:
Name
value
string
Example:
Jane Smith
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reports/contacts_summary/preview HTTP/1.1 

Content-Type: application/json

{
    "filters_set": [
        {
            "key": "period_from",
            "value": "This month"
        }
    ],
    "columns_set": [
        {
            "key": "product_code"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "fields":[
                {            
                    "key": "Name",
                    "value": "Jane Smith"
                }
            ]
        }
    ]
}
Run Report
POST /reports/{name}

Schedule a report and sends its results via email to a group of recipients

Path variables

name
string required

The report (unique name) that will be scheduled

Enumeration:
contacts_summary
contacts_orders_analysis
order_details
contacts_rewards_analysis
organisations_rewards_analysis
organisations_rewards_statement
reward_offer_performance
devices_summary
subscriptions_summary
service_requests_summary
service_requests_analysis

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
format
string required

The report’s format

Enumeration:
PDF
CSV
filters_set
Array required

Set of filters based on which the report runs

Min items: 1
Unique items: YES
Object
label
string required

The filter’s label

Example:
Registration date
key
string required

The filter’s name

Example:
period_from
value
string required

The filter’s value as this was specified by the user

Example:
THIS_MONTH
type
string required

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
columns_set
Array required

Set of columns that will be included in the report

Min items: 1
Example:
Number, Name
Object
order
integer required

The ordering of the columns from left to right

Example:
1
label
string required

The column’s label as this will be displayed on the report

Example:
Code
key
string required

The field’s name

Example:
product_code
type
string required

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
group_by_set
Array nullable

Set of fields to be used to group the report’s results

Object
order
integer required

The grouping’s ordering

Example:
1
label
string required

The group by field’s label as this will be displayed on the report

Example:
Type
key
string required

The field’s name

Example:
product_type
type
string required

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
name
string nullable

Defines the scheduled report name (if not provided will be set based on the report’s unique name, e.g. Contacts Summary)

Example:
VIP Contacts
scheduler_options
Object nullable

Defines the scheduler settings that will send a report on a recurring basis (if not specified, report will be generated and send only once)

period
string required

Defines the period when report generation will take place

Enumeration:
DAILY
WEEKLY
MONTHLY
frequency
string required

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
recipients
Array nullable

Defines the recipients that will receive the report results (if not specified, will be send to the user that requested such report)

Object
recipient_type
string required

The type of recipients that will retrieve the report

Enumeration:
TEAM

Applicable only to Business organisations

USER
recipient_id
string GUID required

The recipients that will retrieve the report

Example:
b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2

Runs a report and sends its results via email to the user who runs it

POST https://sandbox.crm.com/backoffice/v1/reports/contacts_summary HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "format": "CSV",
    "filters_set": [
        {
            "label": "Registration date",
            "key": "period_from",
            "value": "THIS_MONTH",
            "type": "INTEGER"
        }
    ],
    "columns_set": [
        {
            "order": 1,
            "label": "Code",
            "key": "product_code",
            "type": "INTEGER"
        }
    ],
    "group_by_set": [
        {
            "order": 1,
            "label": "Type",
            "key": "product_type",
            "type": "TEXT"
        }
    ]
}

HTTP/1.1 200 OK 

Schedule a report to be send on a recurring basis and send to users of a specific team

POST https://sandbox.crm.com/backoffice/v1/reports/contacts_summary HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "format": "PDF",
    "filters_set": [
        {
            "label": "Registration date",
            "key": "period_from",
            "value": "THIS_MONTH",
            "type": "TEXT"
        }
    ],
    "columns_set": [
        {
            "order": 1,
            "label": "Code",
            "key": "product_code",
            "type": "INTEGER"
        }
    ],
    "group_by_set": [
        {
            "order": 1,
            "label": "Type",
            "key": "product_type",
            "type": "INTEGER"
        }
    ],
    "scheduler_options": {
        "period": "MONTHLY",
        "frequency": "0 0 12 * * ?"
    },
    "recipients": [
        {
            "recipient_type": "TEAM",
            "recipient_id": "b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39"
        }
    ]
}

HTTP/1.1 200 OK
Update Report
PUT /reports/{id}

Schedule a report and sends its results via email to a group of recipients

Path variables

id
string GUID required

The report (identifier) that will be updated

Example:
81228876-09c6-cc46-638d-be2a7a6867bf

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
format
string required

The report’s format

Enumeration:
PDF
CSV
scheduler_options
Object nullable

Defines the scheduler settings that will send a report on a recurring basis (if not specified, report will be generated and send only once)

period
string required

Defines the period when report generation will take place

Enumeration:
DAILY
WEEKLY
MONTHLY
frequency
string required

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
recipients
Array nullable

Defines the recipients that will receive the report results (if not specified, will be send to the user that requested such report)

Object
recipient_type
string required

The type of recipients that will retrieve the report

Enumeration:
TEAM

Applicable only to Business organisations

USER
recipient_id
string GUID required

The recipients that will retrieve the report

Example:
b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39

Responses

200 OK
Body
Object
id
string GUID

The report identifier

Example:
81228876-09c6-cc46-638d-be2a7a6867bf
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/reports/81228876-09c6-cc46-638d-be2a7a6867bf HTTP/1.1 

Content-Type: application/json

{
    "format": "CSV",
    "scheduler_options": {
        "period": "DAILY",
        "frequency": "0 0 12 * * ?"
    },
    "recipients": [
        {
            "recipient_type": "USER",
            "recipient_id": "b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "81228876-09c6-cc46-638d-be2a7a6867bf"
}
Delete (Scheduled) Report
DELETE /reports/{id}

Delete a scheduled report

Path variables

id
string GUID required

The report (unique name) that will be scheduled

Example:
1193d47e-f079-3f03-299b-50b7419459af

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/reports/1193d47e-f079-3f03-299b-50b7419459af HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List (Scheduled) Reports
GET /reports

Retrieve all scheduled reports

Request parameters

name
string optional

Filter based on report name

Example:
VIP Customers
type
string optional

Filter based on report type

Enumeration:
contacts_summary
contacts_orders_analysis
order_details
contacts_rewards_analysis
organisations_rewards_analysis
organisations_rewards_statement
reward_offer_performance
devices_summary
subscriptions_summary
service_requests_summary
service_requests_analysis
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
type
string

The type of the event

Enumeration:
contacts_summary
contacts_orders_analysis
order_details
contacts_rewards_analysis
organisations_rewards_analysis
organisations_rewards_statement
reward_offer_performance
devices_summary
subscriptions_summary
service_requests_summary
service_requests_analysis
name
string

The scheduled report name

Example:
VIP Contacts
scheduler_options
Object

Defines the scheduler settings that will send a report on a recurring basis (if not specified, report will be generated and send only once)

period
string

Defines the period when report generation will take place

Enumeration:
DAILY
WEEKLY
MONTHLY
frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
next_scheduled
integer

The next scheduled period to run the report

Example:
1639123750
recipients
Array

Defines the recipients that will receive the report results

Object
type
string

The type of recipients that will retrieve the report

Enumeration:
TEAM

Applicable only to Business organisations

USER
name
string

The recipient name

Example:
John Doe
username
string

The recipient username (applicable for recipients of type == USER)

Example:
johndoe@crm.com
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reports HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "type": "contacts_summary",
            "name": "VIP Contacts",
            "scheduler_options": {
                "period": "DAILY",
                "next_scheduled": 1631182104
            },
            "recipients": [
                {
                    "type": "TEAM",
                    "name": "John Doe",
                    "username": "johndoe@crm.com"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get (Scheduled) Report
GET /reports/{id}

Get details for a specific (scheduled) report

Path variables

id
string GUID required

The (scheduled) report (identifier) that will be retrieved

Example:
df97fe77-84f0-d761-39d6-6d9e1ddf4962

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The (scheduled) report (identifier) that will be retrieved

Example:
df97fe77-84f0-d761-39d6-6d9e1ddf4962
name
string

The scheduled report name

Example:
VIP Contacts
type
string

The type of the event

Enumeration:
contacts_summary
contacts_orders_analysis
order_details
contacts_rewards_analysis
organisations_rewards_analysis
organisations_rewards_statement
reward_offer_performance
devices_summary
subscriptions_summary
service_requests_summary
service_requests_analysis
format
string

The report’s format

Enumeration:
PDF
CSV
filters_set
Array

Details about the filters based on which the report runs

Object
label
string

The filter’s label

Example:
Registration date
key
string

The filter’s name

Example:
period_from
value
string

The filter’s value as this was specified by the user

Example:
THIS_MONTH
type
string

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
columns_set
Array

Details about the columns that will be included in the report

Object
order
integer

The ordering of the columns from left to right

Example:
1
label
string

The column’s label as this will be displayed on the report

Example:
Code
key
string

The field’s name

Example:
product_code
type
string

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
group_by_set
Array

Details about the fields to be used to group the report’s results

Object
order
integer required

The grouping’s ordering

Example:
1
label
string required

The group by field’s label as this will be displayed on the report

Example:
Type
key
string required

The field’s name

Example:
product_type
type
string required

The data type of the filter

Enumeration:
TEXT
NUMBER
INTEGER
DATE
scheduler_options
Object

Defines the scheduler settings that will send a report on a recurring basis (if not specified, report will be generated and send only once)

period
string

Defines the period when report generation will take place

Enumeration:
DAILY
WEEKLY
MONTHLY
frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
next_scheduled
integer

The next scheduled period to run the report

Example:
1639123750
recipients
Array

Details about the recipients that will receive the report results

Object
recipient_type
string

The type of recipients that will retrieve the report

Enumeration:
TEAM

Applicable only to Business organisations

USER
recipient_id
string GUID

The recipients that will retrieve the report

Example:
b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reports/df97fe77-84f0-d761-39d6-6d9e1ddf4962 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "VIP Contacts",
    "type": "contacts_summary",
    "format": "PDF",
    "filters_set": [
        {
            "label": "Registration date",
            "key": "period_from",
            "value": "THIS_MONTH",
            "type": "DATE"
        }
    ],
    "columns_set": [
        {
            "order": 1,
            "label": "Code",
            "key": "product_code",
            "type": "TEXT"
        }
    ],
    "group_by_set": [
        {
            "order": 1,
            "label": "Type",
            "key": "product_type",
            "type": "TEXT"
        }
    ],
    "scheduler_options": {
        "period": "MONTHLY",
        "frequency": "0 0 12 * * ?"
    },
    "recipients": [
        {
            "recipient_type": "TEAM",
            "recipient_id": "b52f4dbb-0ccf-db7a-93b6-2cc35af9fc39"
        }
    ]
}
Get Organisation Analytics
GET /organisations/{id}/analytics

Get analytics for an organisation

Path variables

id
string GUID required

The organisation identifier that is optionally a parent. If the organisation is a Parent an optional paramter can request children in the same response.

Example:
babc8d45-50be-4259-b1bf-c85dee46642f

Request parameters

metrics
string required

Which metrics are required. A list of metrics can be included in the request, comma separated. At least one must be specified.

Enumeration:
NEW_SIGN_UPS
REWARD_PARTICIPANTS
REWARD_PARTICIPANTS_PER_TIER
OPEN_LOOP_PARTICIPANTS
CLOSE_LOOP_PARTICIPANTS
ACTIVE_REWARD_OFFERS
MOST_REWARDED_OFFER
TOTAL_AWARDS
TOTAL_SPENDS
GIVEN_AWARDS
AWARDS_SPEND
AWARDS_SPEND_PER_VISIT
TOP_10_BEST_OFFERS
TOTAL_PURCHASE_AMOUNT
NUMBER_OF_VISITS
MOST_VISITED_VENUES VISITS
MERCHANTS
VENUES
TOTAL_APPLICATIONS_USAGE
REFERRED_BY
WALLET_BALANCE_BREAK_DOWN
ACTIVE_SUBSCRIBERS
INACTIVE_SUBSCRIBERS
NEW_SERVICES
CANCELLED_SERVICES
REGRETTED_SERVICES
SERVICES_IN_TRIAL
DEACTIVATED_sERVICES
ACTIVATED_SERVICES
SERVICES_IN_TRIAL_WITH_FAILED_PAYMENTS
PAID_SERVICES_IN_TRIAL
CANCELLED_SERVICES_IN_TRIAL
CANCELLED_SERVICES_AFTER_TRIAL
NEW_SUBSCRIBERS
REACTIVATED_SUBSCRIPTIONS
REMOVED_SERVICES_AFTER_EXPIRATION
CANCELLED_SERVICES_IN_CONTRACT
CANCELLED_SERVICES_NOT_IN_CONTRACT
RENEWED_SERVICES
EXPIRED_SERVICES
SUBSCRIBER_CHURN_RATE
TRIALS_STARTED_PER_MONTH
AWARDS

Total Awarded Amount and Total Number of Awards and Previous Period Values

SPENDS

Total Spent Amount and Total Number of Spends and Previous Period Values

SPEND_ANALYSIS
TOTAL_INSTANT_SPENDS
TOTAL_REQUEST_SPENDS
TOTAL_AUTO_SPENDS
TOTAL_EXPIRED_AWARDS
TOTAL_AD_HOC_RETURN_AMOUNT
NUMBER_OF_AD_HOC_RETURNS
TOTAL_LOTTERY_AWARD_AMOUNT
TOTAL_REFERRAL_AWARD_AMOUNT
NUMBER_OF_LOTTERY_AWARDS
NUMBER_OF_REFERRALS
NUMBER_OF_ACHIEVEMENTS
REWARDS_ANALYSIS
CUSTOMER_EVENTS_ANALYSIS
AD_HOC_RETURNS
LOTTERY_WINNERS
REFERRALS
PURCHASES
TOTAL_OPEN_SERVICE_REQUESTS
TOTAL_CLOSED_SERVICE_REQUESTS
MOST_POPULAR_CLOSURE_REASON
SERVICE_REQUEST_RESOLUTION_RATE
SERVICE_REQUESTS_ANALYSIS
TOTAL_OPEN_LEADS
TOTAL_WON_LEADS
TOTAL_LOST_LEADS
LEAD_RESOLUTION_RATIO
LEADS_ANALYSIS
NEW_CONTACTS
CONTACT_REFERRALS
ACTIVE_CONTACTS
CONTACTS_USING_APPLICATIONS
CONTACTS_ACTIVITY
APPLICATIONS_USAGE_BREAKDOWN
NEW_ORDERS
COMPLETED_ORDERS
CANCELLED_ORDERS
AVERAGE_ORDER_COMPLETION
TOTAL_ORDER_AMOUNT
MOST_POPULAR_CANCELLATION_REASON
PREFERRED_ORDERING_ORGANISATION
ORDERS_ANALYSIS
frequency
string required

Frequency denotes which metric will be applied for example get the daily or monthly metrics

Enumeration:
OVERALL
DAILY
WEEKLY
MONTHLY
QUARTERLY
HALF_YEARLY
YEARLY
Default:
OVERALL

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID
Example:
9870818f-fac2-1e36-40b0-02a9ce0a5a63
organisation_id
string GUID
Example:
64824e45-ad64-40c5-9ef4-81cb4d88d9b5
organisation_name
string
Example:
Subscription-Billing
merchants
integer
venues
integer
trials
integer
new_sign_ups
integer
referred_by
integer
reward_participants
integer
reward_participants_per_tier
integer
open_loop_reward_participants
integer
close_loop_reward_participants
integer
active_offers
integer
most_awarded_offer
string
total_awards
number
total_spends
integer
given_awards
integer
awards_spend
integer
average_spend_per_visit
number
top_10_best_offers
Array
Object
offer_id
string GUID
Example:
034de72f-2006-4a80-ba49-13c4de5cc31b
offer_name
string
Example:
Register to Sports channel and win 21 BDT
total_award_amount
number
Example:
26.25
total_purchase_amount
number
total_visits
integer
most_visited_venues
string
total_applications_usage
integer
wallets_open_balance
number
wallets_commerse_balance
number
active_subscribers
integer
inactive_subscribers
integer
new_services
integer
cancelled_services
integer
regretted_services
integer
upgraded_services
integer
downgraded_services
boolean
services_in_trial
integer
deactivated_services
integer
activated_services
integer
paid_services_in_trial
integer
cancelled_services_in_trial
integer
new_subscribers
integer
reactivated_subscriptions
integer
removed_services_after_expiration
integer
cancelled_services_in_contract
integer
cancelled_services_not_in_contract
integer
renewed_services
integer
expired_services
integer
subscriber_churn_rate
integer
active_subscriptions_per_billing_period
integer
active_services_per_month
integer
connected_wifi_contacts
integer

The number of contacts auth’d against a WiFi platform

Example:
3
total_wifi_devices
integer

The number of devices auth’d against a WiFi platform

Example:
2
data_allowance_consumption
Object

Details about data allowance (data should be aggregated from child organisations as well)

consumed_allowance
number

The consumed data allownace

Example:
12
remaining_allowance
number

The remaining data allownace

Example:
12.12
total_allowance
number

The total data allownace (consumed + remaining)

Example:
24.12
top_10_organisation_allowance
Array

Details about the top 10 organisations that allowance was consumed

Object
organisation_id
string GUID

The organisation identifier

Example:
8833bf28-e888-a21b-9619-0945f2dd47c1
organisation_name
string

The organisation name

Example:
CRM
total_consumption
number

The total allowance consumed on the organisation

Example:
123.12
total_open_service_requests
integer
total_closed_service_requests
integer
previous_total_open_service_requests
integer
previous_total_closed_service_requests
integer
most_popular_closure_reason
string
previous_most_popular_closure_reason
string
service_requests_analysis
Array
Object
month
string
open_service_requests
integer
closed_service_requests
integer
previous_total_open_leads
string
total_open_leads
integer
total_lost_leads
integer
previous_total_lost_leads
integer
total_won_leads
integer
previous_total_won_leads
integer
leads_analysis
Array
Object
month
string
open_leads
integer
won_leads
integer
lost_leads
integer
new_contacts
integer
previous_new_contacts
integer
referrals
integer
previous_referrals
integer
active_contacts
integer
previous_active_contacts
integer
contacts_using_applications
integer
previous_contacts_using_applications
integer
contacts_activity
Array
Object
month
string
contacts_registered
integer
contacts_using_applications
integer
referrals
integer
applications_usage_breakdown
Object
mobile_applications
integer
portal_applications
integer
other_applications
integer
new_orders
integer
previous_new_orders
integer
completed_orders
integer
previous_completed_orders
integer
cancelled_orders
integer
previous_cancelled_orders
integer
average_order_completion
number
previous_average_order_completion
number
total_order_amount
number
previous_total_order_amount
number
most_popular_cancellation_reason
string
previous_most_popular_cancellation_reason
string
preferred_ordering_organisation
string
previous_preferred_ordering_organisation
string
orders_analysis
Array
Object
month
string
new_orders
integer
completed_orders
integer
cancelled_orders
integer
total_mrr
number
previous_total_mrr
number
new_mrr
number
previous_new_mrr
number
mrr_growth
number
previous_mrr_growth
number
trial_paid_mrr
number
previous_trial_paid_mrr
number
reactivation_mrr
number
previous_reactivation_mrr
number
expand_mrr
number
previous_expand_mrr
string
upgrade_mrr
number
previous_upgrade_mrr
number
sub_expansion_mrr
number
previous_sub_expansion_mrr
number
restart_mrr
number
previous_restart_mrr
number
churn_mrr
number
previous_churn_mrr
number
downgrade_mrr
number
previous_downgrade_mrr
number
cancel_mrr
number
previous_cancel_mrr
number
regret_mrr
number
previous_regret_mrr
number
contact_category_mrr
Array
Object
month
string
mrr
number
service_mrr
Array
Object
month
string
mrr
number
price_term_mrr
Array
Object
month
string
mrr
number
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/babc8d45-50be-4259-b1bf-c85dee46642f/analytics HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "organisation_id": "64824e45-ad64-40c5-9ef4-81cb4d88d9b5",
            "organisation_name": "Subscription-Billing",
            "merchants": 1,
            "venues": 1,
            "trials": 1,
            "new_sign_ups": 1,
            "referred_by": 1,
            "reward_participants": 1,
            "reward_participants_per_tier": 1,
            "open_loop_reward_participants": 1,
            "close_loop_reward_participants": 1,
            "active_offers": 1,
            "most_awarded_offer": "",
            "total_awards": 1,
            "total_spends": 1,
            "given_awards": 1,
            "awards_spend": 1,
            "average_spend_per_visit": 1,
            "top_10_best_offers": [
                {
                    "offer_id": "034de72f-2006-4a80-ba49-13c4de5cc31b",
                    "offer_name": "Register to Sports channel and win 21 BDT",
                    "total_award_amount": 26.25
                }
            ],
            "total_purchase_amount": 1,
            "total_visits": 1,
            "most_visited_venues": "",
            "total_applications_usage": 1,
            "wallets_open_balance": 1,
            "wallets_commerse_balance": 1,
            "active_subscribers": 1,
            "inactive_subscribers": 1,
            "new_services": 1,
            "cancelled_services": 1,
            "regretted_services": 1,
            "upgraded_services": 1,
            "downgraded_services": true,
            "services_in_trial": 1,
            "deactivated_services": 1,
            "activated_services": 1,
            "paid_services_in_trial": 1,
            "cancelled_services_in_trial": 1,
            "new_subscribers": 1,
            "reactivated_subscriptions": 1,
            "removed_services_after_expiration": 1,
            "cancelled_services_in_contract": 1,
            "cancelled_services_not_in_contract": 1,
            "renewed_services": 1,
            "expired_services": 1,
            "subscriber_churn_rate": 1,
            "active_subscriptions_per_billing_period": 1,
            "active_services_per_month": 1
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Contact Analytics
GET /contacts/{id}/analytics

Get analytics for a contact

Path variables

id
string GUID required

The contact (identifier) of which analytics will be retrieved

Example:
babc8d45-50be-4259-b1bf-c85dee46642f

Request parameters

metrics
string required

Filters based on which metrics will be retrieved (a list of metrics can be included in the request, comma separated - and at least one metric should be specified)

Enumeration:
USAGE
frequency
string required

Frequency denotes which metric will be applied for example get the daily or monthly metrics

Enumeration:
OVERALL
DAILY
WEEKLY
MONTHLY
QUARTERLY
HALF_YEARLY
YEARLY
Default:
OVERALL

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
contact
Object

Details about the contact

id
string GUID

The contact identifier

Example:
fa3360fa-a246-7d1e-1c41-eda3c093dcc9
name
string

The contact (full) name

Example:
John R. Doe
usage
Object

Details about contact’s usage

consumed_usage
number

The usage that is already consumed

Example:
20
remaining_usage
number

The remaining usage that can be consumed

Example:
80
usage_percentage
number

The percentage relation between consumed and allowed usage

Example:
20
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/babc8d45-50be-4259-b1bf-c85dee46642f/analytics?metrics=USAGE&frequency=OVERALL HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "contact": {
        "id": "fa3360fa-a246-7d1e-1c41-eda3c093dcc9",
        "name": "John R. Doe"
    },
    "usage": {
        "consumed_usage": 20,
        "remaining_usage": 80,
        "usage_percentage": 20
    }
}
Attachment Files & Media

Storing and managing of attachment files and creative assets for many entities

Attachment Files
POST /upload/files
DELETE /files/{id}
GET /files/{id}
Upload File
POST /upload/files

Create an upload signature for files

Notes

Uploading files into CRM is made based on the following flow & API calls

  1. Upload File Signature
  2. Connect File to a “Module” Entity, such as Service Request Files

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

multipart/form-data
application/json
Object
file
string required

File contents provided via multipart/form-data

Example:
file object

Responses

200 OK
Body
Object
id
string GUID

The file identifier that will be used for connecting the file with a module

Example:
7279fecf-b0a6-0aab-6bcd-37881fe8c10e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/upload/files HTTP/1.1 

Content-Type: multipart/form-data
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "file": "file object"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7279fecf-b0a6-0aab-6bcd-37881fe8c10e"
}
Delete File
DELETE /files/{id}

Delete an existing file

Path variables

id
string GUID required

The file (identifier) to be deleted

Example:
5f21680e-2ce4-7b4b-7221-42cc2a41bc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/files/5f21680e-2ce4-7b4b-7221-42cc2a41bc05 HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 
Get File
GET /files/{id}

Retrieve a specific file

Path variables

id
string GUID required

The file (identifier) to be retrieved

Example:
5f21680e-2ce4-7b4b-7221-42cc2a41bc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The file identifier

Example:
3ae9d64a-8a3b-f1e1-eed6-05b307f926fb
content_url
string

The URL that can be used to access the actual content of the file

Example:
crm.com/file
mime
string

The mime type of the uploaded file

Enumeration:
csv
doc
docx
xls
xlsx
pdf
log
txt
png
jpg
jpeg
svg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/files/5f21680e-2ce4-7b4b-7221-42cc2a41bc05 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
    "content_url": "crm.com/file",
    "mime": "txt"
}
Media
POST /upload/media
DELETE /media/{id}
POST /mediagroups
POST /upload/sign
Upload Media
POST /upload/media

Create an upload media

Notes

Uploading media into CRM is made based on the following flow & API calls

  1. Create new Media Group
  2. Create “Module” Media Group, such as Product Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
media_group_external_id
string GUID required

The media group (identifier) to associate the media item with once uploaded (external id is based on the response of Create new Media Group)

Example:
e66896ba-db0a-41e2-8093-9aca2ae02f29
media_usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
folder
string required

The related Cloudinary folder (within CRM the folder is set as the media related organisation-id)

Example:
offers/hero
tracking_key
string GUID required

The key to track upload (random UUID)

Example:
26c32dfe-f8ea-9cf3-a5af-5096be4a164b

Responses

200 OK
Body
Object
api_key
string

The API key that is used for uploading media

Example:
698271538719998
cloud_name
string

The name of the cloudinary instance

Example:
crm-com
context
string

The uploaded signature context

Example:
uploadStrategy=MEDIA_UPLOAD|organisationId=8062c26a-c05f-47ca-81e4-566b3c279320|trackingKey=e3ffca89-902f-4bd6-b503-c7dcf59dd725|mediaGroupExternalId=1d7b73d2-a324-4cee-a97a-492050b101ef|usageType=ATTACHMENT
signature
string

The uploaded signature value

Example:
8f38472a40d8466f11852bd9d3a19c23bfe12f91
timestamp
integer epoch

The date/time on which such upload was made

Example:
1616056261
upload_options
Array

Details about the upload options

Object
folder
string GUID

The folder in which media will be uploaded (and located)

Example:
35d7d0a4-9846-73a7-8707-26d2507edc51
media_group_external_id
string GUID

The media group external identifier

Example:
35d7d0a4-9846-73a7-8707-26d2507edc51
media_usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
options
Object

Defines how media will be used

type
string

The option type (defaults to upload)

Example:
upload
needed_signature_options
Object

Details that will be used in the signature

folder
string GUID

The folder in which media will be uploaded (and located)

Example:
6ff2469c-e473-e370-c86e-16633434607a
type
string

Defines what action will be performed on the media (always is set to “upload”)

Example:
upload
tracking_key
string GUID

The key to track the current upload

Example:
6ff2469c-e473-e370-c86e-16633434607a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/upload/media HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "media_group_external_id": "e66896ba-db0a-41e2-8093-9aca2ae02f29",
    "media_usage_type": "LOGO",
    "folder": "offers/hero",
    "tracking_key": "26c32dfe-f8ea-9cf3-a5af-5096be4a164b"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "api_key": "698271538719998",
    "cloud_name": "crm-com",
    "context": "uploadStrategy=MEDIA_UPLOAD|organisationId=8062c26a-c05f-47ca-81e4-566b3c279320|trackingKey=e3ffca89-902f-4bd6-b503-c7dcf59dd725|mediaGroupExternalId=1d7b73d2-a324-4cee-a97a-492050b101ef|usageType=ATTACHMENT",
    "signature": "8f38472a40d8466f11852bd9d3a19c23bfe12f91",
    "timestamp": 1616056261,
    "upload_options": [
        {
            "folder": "35d7d0a4-9846-73a7-8707-26d2507edc51",
            "media_group_external_id": "35d7d0a4-9846-73a7-8707-26d2507edc51",
            "media_usage_type": "MARKETING",
            "options": {
                "type": "upload"
            },
            "needed_signature_options": {
                "folder": "6ff2469c-e473-e370-c86e-16633434607a",
                "type": "upload"
            },
            "tracking_key": "6ff2469c-e473-e370-c86e-16633434607a"
        }
    ]
}
Delete Media
DELETE /media/{id}

Delete an existing media

Path variables

id
string GUID required

The media (identifier) to be deleted

Example:
5f21680e-2ce4-7b4b-7221-42cc2a41bc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/media/5f21680e-2ce4-7b4b-7221-42cc2a41bc05 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Create Media Group
POST /mediagroups

Create a new group for upcoming uploaded media

Notes

MEDIA UPLOAD

Uploading media for an entity requires the execution of the following APIs

  1. Create new Media Group
  2. Create “Module” Media Group, such as Product Media Groups
  3. Upload Signature
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The media group name

Example:
Marketing
description
string nullable

The media group description

Example:
Marketing Media Group for Creatives
externalId
string GUID required

The media group external identifier

Example:
747e5a96-24a2-7aca-7b28-da5e996ad54c

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/media_group HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Marketing",
    "description": "Marketing Media Group for Creatives",
    "externalId": "747e5a96-24a2-7aca-7b28-da5e996ad54c"
}

HTTP/1.1 200 OK 
Upload Signature
POST /upload/sign

Create an upload signature

Notes

Uploading media into CRM is made based on the following flow & API calls

  1. Create new Media Group
  2. Create “Module” Media Group, such as Product Media Groups
  3. Upload Signature
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
mediaGroupExternalId
string GUID required

The media group (identifier) to associate the media item with once uploaded (external id is based on the response of Create new Media Group)

Example:
e66896ba-db0a-41e2-8093-9aca2ae02f29
mediaUsageType
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
folder
string required

The related Cloudinary folder (within CRM the folder is set as the media related organisation-id)

Example:
offers/hero
trackingKey
string GUID required

The key to track upload (random UUID)

Example:
26c32dfe-f8ea-9cf3-a5af-5096be4a164b

Responses

200 OK
Body
Object
apiKey
string

The API key that is used for uploading media

Example:
698271538719998
cloudName
string

The name of the cloudinary instance

Example:
crm-com
context
string

The uploaded signature context

Example:
uploadStrategy=MEDIA_UPLOAD|organisationId=8062c26a-c05f-47ca-81e4-566b3c279320|trackingKey=e3ffca89-902f-4bd6-b503-c7dcf59dd725|mediaGroupExternalId=1d7b73d2-a324-4cee-a97a-492050b101ef|usageType=ATTACHMENT
signature
string

The uploaded signature value

Example:
8f38472a40d8466f11852bd9d3a19c23bfe12f91
timestamp
integer epoch

The date/time on which such upload was made

Example:
1616056261
uploadOptions
Array

Details about the upload options

Object
folder
string GUID

The folder in which media will be uploaded (and located)

Example:
35d7d0a4-9846-73a7-8707-26d2507edc51
mediaGroupExternalId
string GUID

The media group external identifier

Example:
35d7d0a4-9846-73a7-8707-26d2507edc51
mediaUsageType
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
options
Object
type
string
Example:
upload
optionsNeededInSignature
Object
folder
string GUID
Example:
6ff2469c-e473-e370-c86e-16633434607a
type
string
Example:
upload
trackingKey
string GUID

The key to track the current upload

Example:
6ff2469c-e473-e370-c86e-16633434607a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/upload/sign HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "mediaGroupExternalId": "e66896ba-db0a-41e2-8093-9aca2ae02f29",
    "mediaUsageType": "AVATAR",
    "folder": "a01ad9a4-5c9f-e676-fbcb-b0d03c51f022",
    "trackingKey": "a01ad9a4-5c9f-e676-fbcb-b0d03c51f044"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "apiKey": "698271538719998",
    "cloudName": "crm-com",
    "context": "uploadStrategy=MEDIA_UPLOAD|organisationId=8062c26a-c05f-47ca-81e4-566b3c279320|trackingKey=e3ffca89-902f-4bd6-b503-c7dcf59dd725|mediaGroupExternalId=1d7b73d2-a324-4cee-a97a-492050b101ef|usageType=ATTACHMENT",
    "signature": "8f38472a40d8466f11852bd9d3a19c23bfe12f91",
    "timestamp": 1616056261,
    "uploadOptions": [
        {
            "folder": "35d7d0a4-9846-73a7-8707-26d2507edc51",
            "mediaGroupExternalId": "35d7d0a4-9846-73a7-8707-26d2507edc51",
            "mediaUsageType": "ATTACHMENT",
            "options": {
                "type": "upload"
            },
            "optionsNeededInSignature": {
                "folder": "6ff2469c-e473-e370-c86e-16633434607a",
                "type": "upload"
            },
            "trackingKey": "6ff2469c-e473-e370-c86e-16633434607a"
        }
    ]
}
Automations
POST /automations
PUT /automations/{id}
DELETE /automations/{id}
GET /automations
GET /automations/{id}
POST /automations/{id}/actions
GET /automations/{id}/actions
Create Automation
POST /automations

Create a new automation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The automation name

Example:
Approve Offers
description
string nullable

The automation description

Example:
Require 4 approvals for an offer
life_cycle_state
string nullable

The automation state

Enumeration:
ACTIVE
INACTIVE
Default:
INACTIVE
entity
string required

Defines the entity that its events will trigger this automation

Enumeration:
APPROVALS
CONTACTS
CUSTOMER_EVENTS
FINANCIAL_TRANSACTIONS
ORDERS
ORGANISATIONS
PASSES
PRODUCTS
REWARDS
REWARD_OFFERS
REWARD_SCHEMES
SERVICE_REQUEST
SUBSCRIPTIONS
USERS
event
string required

Defines the event that will trigger this automation (filtered based on the selected entity)

Enumeration:
APPROVE_ALL_REQUESTS

Approvals

REJECT_REQUESTS

Approvals

REFER_A_FRIEND

Contacts

REGISTER_CONTACT

Contacts

UPDATE_CONTACT

Contacts

REQUEST_ONE_TIME_PASSWORD

ContactsContacts

REQUIRE_EMAIL_VERIFICATION

Contacts

REQUEST_PASSWORD_RESET

Contacts & Users

NEW_ORDER

Orders

ORDER_INITIATION

Orders

ORDER_COMPLETION

Orders

ORDER_CANCELLATION

Orders

GENERATE_PRINTED_PASSES

Passes

GENERATE_ELECTRONIC_PASSES

Passes

AWARD_CUSTOMER

Rewards

SPEND_AWARD

Rewards

ACTIVATE_REWARD_OFFER

Reward Offers

REQ_TO_JOIN_CLOSE_LOOP_SCHEME

Reward Schemes

NEW_SERVICE_REQUEST

Service Requests

REGISTER_ORGANISATION

Organisations

VALIDATE_REGISTER_ORGANISATION

Organisations

INVITE_USER

Users

INVITE_EXISTING_USER

Users

PRODUCT_SYNCHRONISATION

Products

NEW_REFUND

Financial Transactions

NEW_INVOICE

Financial Transactions

NEW_CREDIT_NOTE

Financial Transactions

NEW_PAYMENT

Financial Transactions

NEW_TOP_UP

Financial Transactions

NEW_PURCHASE

Customer Events

CANCEL_PURCHASE

Customer Events

AD_HOC_RETURN_PURCHASE

Customer Events

NEW_SUBSCRIPTION

Subscriptions

ADD_SUB_SERV

Subscriptions

CANCEL_SUB_SERV

Subscriptions

REGRET_SUB_SERV

Subscriptions

UPGRADE_SUB_SERV

Subscriptions

DOWNGRADE_SUB_SERV

Subscriptions

ACTIVATE_SUB_SERV

Subscriptions

DEACTIVATE_SUB_SERV

Subscriptions

PAUSE_SUB_SERV

Subscriptions

RESUME_SUB_SERV

Subscriptions

OPT_SUB_SERV_IN_AUTO_RENEW

Subscriptions

OPT_SUB_SERV_OUT_AUTO_RENEW

Subscriptions

EXTEND_SUB_SERV_TERM_PERIOD

Subscriptions

EXTEND_SUB_SERV_CONT_PERIOD

Subscriptions

RENEW_SUB_SERV_TERM_PERIOD

Subscriptions

RENEW_SUB_SERV_CONT_PERIOD

Subscriptions

ADD_ONE_TIME_SERVICE

Subscriptions

PAYMENT_FAILURE

Financial Transactions

Responses

201 Created

The requested succeded

Body
Object
id
string GUID

The automation identifier

Example:
890108f6-0237-d984-a367-2f9502dc2acc
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/automations HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Approve Offers",
    "description": "Require 4 approvals for an offer",
    "state": "INACTIVE",
    "entity": "ORDERS",
    "event": "ORDER_INITIATION"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "890108f6-0237-d984-a367-2f9502dc2acc"
}
Update Automation
PUT /automations/{id}

Update an existing automation

Path variables

id
string GUID required

The automation (identifier) that will be updated

Example:
QWERTY1234543212345678UJIKY76HJR

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The automation name

Example:
Approve Offers
description
string nullable

The automation description

Example:
Require 4 approvals for an offer
life_cycle_state
string nullable

Defines whether the automation is active or not

Enumeration:
ACTIVE
INACTIVE

Responses

200 200

Successful Request

Body
Object
id
string GUID

The automation identifier that was updated

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/automations/QWERTY1234543212345678UJIKY76HJR HTTP/1.1 

Content-Type: application/json

{
    "name": "Approve Offers",
    "description": "Require 4 approvals for an offer",
    "life_cycle_state": "ACTIVE"
}
Delete Automation
DELETE /automations/{id}

Delete an existing automation

Path variables

id
string GUID required

The automation (identifier) that will be deleted

Example:
QWERTY1234543212345678UJIKY76HJR

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/automations/QWERTY1234543212345678UJIKY76HJR HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Automations
GET /automations

Search for automations

Request parameters

search_value
string optional

Search automations based on Name

Example:
Notify customers on award
name
string optional

Filter based on automation name

Example:
Notify customers on award
life_cycle_state
string optional

Filter based on automation state

Enumeration:
ACTIVE
INACTIVE
entity
string optional

Filter based on the entity that its event will trigger the automation

event
string optional

Filter based on the event that will trigger the automation

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The automation identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The automation name

Example:
Notify customers on award
description
string

The automation description

Example:
Lorem Ipsum
life_cycle_state
string

The automation state

Enumeration:
ACTIVE
INACTIVE
entity
string

Defines the entity that its events will trigger this automation

Enumeration:
APPROVALS
CONTACTS
CUSTOMER_EVENTS
FINANCIAL_TRANSACTIONS
ORDERS
ORGANISATIONS
PASSES
PRODUCTS
REWARDS
REWARD_OFFERS
REWARD_SCHEMES
SERVICE_REQUEST
SUBSCRIPTIONS
USERS
event
string

Defines the event that will trigger this automation (filtered based on the selected entity)

Enumeration:
APPROVE_ALL_REQUESTS

Approvals

REJECT_REQUESTS

Approvals

REFER_A_FRIEND

Contacts

REGISTER_CONTACT

Contacts

UPDATE_CONTACT

Contacts

REQUEST_ONE_TIME_PASSWORD

ContactsContacts

REQUIRE_EMAIL_VERIFICATION

Contacts

REQUEST_PASSWORD_RESET

Contacts & Users

NEW_ORDER

Orders

ORDER_INITIATION

Orders

ORDER_COMPLETION

Orders

ORDER_CANCELLATION

Orders

GENERATE_PRINTED_PASSES

Passes

GENERATE_ELECTRONIC_PASSES

Passes

AWARD_CUSTOMER

Rewards

SPEND_AWARD

Rewards

ACTIVATE_REWARD_OFFER

Reward Offers

REQ_TO_JOIN_CLOSE_LOOP_SCHEME

Reward Schemes

NEW_SERVICE_REQUEST

Service Requests

REGISTER_ORGANISATION

Organisations

VALIDATE_REGISTER_ORGANISATION

Organisations

INVITE_USER

Users

INVITE_EXISTING_USER

Users

PRODUCT_SYNCHRONISATION

Products

NEW_REFUND

Financial Transactions

NEW_INVOICE

Financial Transactions

NEW_CREDIT_NOTE

Financial Transactions

NEW_PAYMENT

Financial Transactions

NEW_TOP_UP

Financial Transactions

NEW_PURCHASE

Customer Events

CANCEL_PURCHASE

Customer Events

AD_HOC_RETURN_PURCHASE

Customer Events

NEW_SUBSCRIPTION

Subscriptions

ADD_SUB_SERV

Subscriptions

CANCEL_SUB_SERV

Subscriptions

REGRET_SUB_SERV

Subscriptions

UPGRADE_SUB_SERV

Subscriptions

DOWNGRADE_SUB_SERV

Subscriptions

ACTIVATE_SUB_SERV

Subscriptions

DEACTIVATE_SUB_SERV

Subscriptions

PAUSE_SUB_SERV

Subscriptions

RESUME_SUB_SERV

Subscriptions

OPT_SUB_SERV_IN_AUTO_RENEW

Subscriptions

OPT_SUB_SERV_OUT_AUTO_RENEW

Subscriptions

EXTEND_SUB_SERV_TERM_PERIOD

Subscriptions

EXTEND_SUB_SERV_CONT_PERIOD

Subscriptions

RENEW_SUB_SERV_TERM_PERIOD

Subscriptions

RENEW_SUB_SERV_CONT_PERIOD

Subscriptions

ADD_ONE_TIME_SERVICE

Subscriptions

PAYMENT_FAILURE

Financial Transactions

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/automations HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "name": "Notify customers on award",
            "description": "Lorem Ipsum",
            "life_cycle_state": "INACTIVE",
            "entity": "Contacts",
            "event": "Register Customer"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Automation
GET /automations/{id}

Get details for a specific automation

Path variables

id
string GUID required

The automation (identifier) that will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The automation identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The automation name

Example:
Notify awarded customers
description
string

The automation description

Example:
On customer award an outbound email communication will be triggered
life_cycle_state
string

The automation state

Enumeration:
ACTIVE
INACTIVE
entity
string

Defines the entity that its events will trigger this automation

Enumeration:
APPROVALS
CONTACTS
CUSTOMER_EVENTS
FINANCIAL_TRANSACTIONS
ORDERS
ORGANISATIONS
PASSES
PRODUCTS
REWARDS
REWARD_OFFERS
REWARD_SCHEMES
SERVICE_REQUEST
SUBSCRIPTIONS
USERS
event
string

Defines the event that will trigger this automation (filtered based on the selected entity)

Enumeration:
APPROVE_ALL_REQUESTS

Approvals

REJECT_REQUESTS

Approvals

REFER_A_FRIEND

Contacts

REGISTER_CONTACT

Contacts

UPDATE_CONTACT

Contacts

REQUEST_ONE_TIME_PASSWORD

ContactsContacts

REQUIRE_EMAIL_VERIFICATION

Contacts

REQUEST_PASSWORD_RESET

Contacts & Users

NEW_ORDER

Orders

ORDER_INITIATION

Orders

ORDER_COMPLETION

Orders

ORDER_CANCELLATION

Orders

GENERATE_PRINTED_PASSES

Passes

GENERATE_ELECTRONIC_PASSES

Passes

AWARD_CUSTOMER

Rewards

SPEND_AWARD

Rewards

ACTIVATE_REWARD_OFFER

Reward Offers

REQ_TO_JOIN_CLOSE_LOOP_SCHEME

Reward Schemes

NEW_SERVICE_REQUEST

Service Requests

REGISTER_ORGANISATION

Organisations

VALIDATE_REGISTER_ORGANISATION

Organisations

INVITE_USER

Users

INVITE_EXISTING_USER

Users

PRODUCT_SYNCHRONISATION

Products

NEW_REFUND

Financial Transactions

NEW_INVOICE

Financial Transactions

NEW_CREDIT_NOTE

Financial Transactions

NEW_PAYMENT

Financial Transactions

NEW_TOP_UP

Financial Transactions

NEW_PURCHASE

Customer Events

CANCEL_PURCHASE

Customer Events

AD_HOC_RETURN_PURCHASE

Customer Events

NEW_SUBSCRIPTION

Subscriptions

ADD_SUB_SERV

Subscriptions

CANCEL_SUB_SERV

Subscriptions

REGRET_SUB_SERV

Subscriptions

UPGRADE_SUB_SERV

Subscriptions

DOWNGRADE_SUB_SERV

Subscriptions

ACTIVATE_SUB_SERV

Subscriptions

DEACTIVATE_SUB_SERV

Subscriptions

PAUSE_SUB_SERV

Subscriptions

RESUME_SUB_SERV

Subscriptions

OPT_SUB_SERV_IN_AUTO_RENEW

Subscriptions

OPT_SUB_SERV_OUT_AUTO_RENEW

Subscriptions

EXTEND_SUB_SERV_TERM_PERIOD

Subscriptions

EXTEND_SUB_SERV_CONT_PERIOD

Subscriptions

RENEW_SUB_SERV_TERM_PERIOD

Subscriptions

RENEW_SUB_SERV_CONT_PERIOD

Subscriptions

ADD_ONE_TIME_SERVICE

Subscriptions

PAYMENT_FAILURE

Financial Transactions

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/automations/CEEE83D6E0804A30966F684B0269AD91 HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "name": "Notify awarded customers",
    "description": "On customer award an outbound email communication will be triggered",
    "life_cycle_state": "INACTIVE",
    "entity": "CONTACTS",
    "event": "AWARD_CUSTOMER"
}
Add Automation Actions
POST /automations/{id}/actions

Set the sequence of actions (including filters) for a specific automation

Path variables

id
string GUID required

The automation (identifier) whose sequence will be set

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
content
Array
Object
id
string GUID required nullable

The automation action identifier

Example:
ACTIONB5E44F44B28451FE021FCAD51E
order
integer required

Defines the sequence’s action

Example:
1
path
string

Defines the sequence path

Example:
1
adaptor
string required

The automation adaptor

Enumeration:
APPROVAL_REQUESTS

Approval Requests

AUTOMATIC_CONTENT_UPDATES

Automatic Content Updates

COMMUNICATIONS

Communications

ORDER_PROVISIONING

Order Provision

SERVICE_REQUEST_PROVISION

Service Request Provision

WEBHOOKS

Webhooks

MICROS_SIMPHONY_ORDER_PROV

MICROS Simphony Order Provision

NCR_ALOHA_ORDER_PROVISIONING

NCR Aloha Order Provision

CUSTOMER_EVENTS
adaptor_action
string required

The automation adaptor action (each action is applicable for specific adaptors)

Enumeration:
USER_APPROVAL

Request User Appoval (Approval Requests adaptor)

CONTACT_APPROVAL

Request Customer Appoval (Approval Requests adaptor)

UPDATE_CONTENT

Update Content (Automatic Content Updates adaptor)

COMMUNICATE_CUSTOMER

Communicate Customer (Communications adaptor)

COMMUNICATE_USER

Communicate User (Communications adaptor)

ASSIGN_SPECIFIC_USER

Assign To A Specific User (Order Provision & Service Request Provision adaptor)

FF_BY_SPECIFIC_ORGANISATION

Fulfilled By Specific Organisation (Order Provision & Service Request Provision adaptor)

ASSIGN_SPECIFIC_TEAM

Assign To Specific Team (Order Provision adaptor)

FULFILLED_BY_NEAREST_LOCATION

Fulfilled By Nearest Location (Order Provision adaptor)

FF_BASED_ON_POST_CODE_COVERAGE

Fulfilled Based On Post Code Coverage (Order Provision adaptor)

POST_WEBHOOK

POST Webhook (webhooks adaptor)

PUT_WEBHOOK

Put Webhook (webhooks adaptor)

ASSIGN_USER_OF_SPECIFIC_TEAM

Assign To User Of A Specific Team (Service Request Provision adaptor)

ASSIGN_USER_OF_SPEC_USER_ROLE

Assign To User Of A Specific User Role (Service Request Provision adaptor)

FF_BY_USER_OF_SPEC_USER_ROLE

Fulfilled By User Of A Specific User Role (Service Request Provision adaptor)

FULFILLED_BY_SPECIFIC_USER

Fulfilled By Specific User (Service Request Provision adaptor)

PROV_ORDER_TO_SIMPHONY_POS

Provision Order To Simphony POS (MICROS Simphony Order Provision adaptor)

PROV_ORDER_TO_ALOHA_POS

Provision Order To Aloha POS (NCR Aloha Order Provision adaptor)

POST_PURCHASE
CANCEL_PURCHASE
adaptor_action_parameters
Array

Details about the adaptor’s actions parameters

Object
id
string GUID nullable

The parameter identifier

Example:
4b8e0ae7-0f8a-4313-a1fd-ecc1c0510f55
parameter_group
string required

The parameter group (used when more than one parameters should be specified for an adaptor’s action)

Example:
1
parameter_key
string required

The parameter key

Enumeration:
COMMUNICATION_PLAN
USERS_COMMUNICATE_USERS_ID
USERS_COMMUNICATE_USER_ROLE_ID
ASSIGN_ORDER_ORGANISATION_ID
ASSIGN_ORDER_USER_ID
FULFILL_ORDER_DISTANCE
FULFILL_ORDER_ORGANISATION_ID
FULFILL_ORDER_POSTAL_CODE
FULFILL_ORDER_POSTAL_CODE_RANGE
WEBHOOK
CUSTOMER_EVENT_CLASSIFICATION
WITHIN_ORGANISATIONS
parameter_from_value
string required

The parameter from value

Example:
123
parameter_to_value
string nullable

The parameter to value

Example:
1234
parameter_type
string

The parameter type

Enumeration:
DATE
INTEGER
NUMBER
STRING
action_filters
Array

Details about the filters to be applied (required when type is based on Filter)

Object
filters
Array required

Details about the applicable filtered attributes

Object
id
string GUID nullable

The filter identiifer

Example:
edd5ac0e-05e3-e543-d38e-c6df6eed8d46
custom_field_key
string nullable

The custom field that its value will be compared based on the related operator

Example:
contact_salary
attribute
string required

The attribute that its value will be compared based on the related operator

Enumeration:
SUPPLY_METHOD
PASS_CLASSIFICATION
REWARD_OFFER_GOAL
REWARD_OFFER_TYPE
REWARD_OFFER_SPEND_METHOD("
REWARD_OFFER_AWARD_AMOUNT("
REWARD_OFFER_AWARD_PERCENTAGE
ENTITY_CUSTOM_FIELD
CONACT_CUSTOM_FIELD
type
string required

The type of the key

Enumeration:
STRING
INTEGER
NUMBER
DATE
operator
string required

The filter operator to compare the attribute actual value with the filtered one

Enumeration:
EQUAL

Applicable for type of number/integer/date

IS

Applicable for type of string

EQUAL_GREATER

Applicable for type of number/integer/date

EQUAL_LESS

Applicable for type of number/integer/date

LESS

Applicable for type of number/integer/date

GREATER

Applicable for type of number/integer/date

value
string required nullable

The attribute value to apply the filter condition (either value or value_list should be specified)

Example:
123
value_list
Array of string required nullable

The supported list of values (either value or value_list should be specified)

Responses

200 200

OK

Body
Object
id
string GUID

The automation identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/automations/6A24D2B5E44F44B28451FE021FCAD51E/actions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "content": [
        {
            "id": "ACTIONB5E44F44B28451FE021FCAD51E",
            "adaptor": "APPROVAL_REQUESTS",
            "adaptor_action": "ASSIGN_SPECIFIC_DEPARTMENT",
            "order": 1,
            "path": "1",
            "adaptor_action_parameters": [
                {
                    "id": "4b8e0ae7-0f8a-4313-a1fd-ecc1c0510f55",
                    "parameter_group": "1",
                    "parameter_key": "RICH_CONTENT",
                    "parameter_from_value": "123",
                    "parameter_to_value": "1234",
                    "parameter_type": "APPROVAL_ENTITY_TYPE"
                }
            ],
            "action_filters": [
                {
                    "filters": [
                        {
                            "id": "edd5ac0e-05e3-e543-d38e-c6df6eed8d46",
                            "attribute": "NAME",
                            "type": "NUMBER",
                            "operator": "EQUAL_LESS",
                            "value": "123",
                            "value_list": [
                                ""
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E"
}
Get Automation Actions
GET /automations/{id}/actions

Retrieves the automation’ sequence of actions (including filters)

Path variables

id
string GUID required

The automation (identifier) whose actions will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string

The automation action identifier

Example:
ACTIONB5E44F44B28451FE021FCAD51E
order
integer

Defines the sequence’s action

Example:
1
adaptor
string

The automation adaptor

Enumeration:
APPROVAL_REQUESTS

Approval Requests

AUTOMATIC_CONTENT_UPDATES

Automatic Content Updates

COMMUNICATIONS

Communications

ORDER_PROVISIONING

Order Provision

SERVICE_REQUEST_PROVISION

Service Request Provision

WEBHOOKS

Webhooks

MICROS_SIMPHONY_ORDER_PROV

MICROS Simphony Order Provision

NCR_ALOHA_ORDER_PROVISIONING

NCR Aloha Order Provision

CUSTOMER_EVENTS
adaptor_action
string

The automation adaptor action (each action is applicable for specific adaptors)

Enumeration:
USER_APPROVAL

Request User Appoval (Approval Requests adaptor)

CONTACT_APPROVAL

Request Customer Appoval (Approval Requests adaptor)

UPDATE_CONTENT

Update Content (Automatic Content Updates adaptor)

COMMUNICATE_CUSTOMER

Communicate Customer (Communications adaptor)

COMMUNICATE_USER

Communicate User (Communications adaptor)

ASSIGN_SPECIFIC_USER

Assign To A Specific User (Order Provision & Service Request Provision adaptor)

FF_BY_SPECIFIC_ORGANISATION

Fulfilled By Specific Organisation (Order Provision & Service Request Provision adaptor)

ASSIGN_SPECIFIC_TEAM

Assign To Specific Team (Order Provision adaptor)

FULFILLED_BY_NEAREST_LOCATION

Fulfilled By Nearest Location (Order Provision adaptor)

FF_BASED_ON_POST_CODE_COVERAGE

Fulfilled Based On Post Code Coverage (Order Provision adaptor)

POST_WEBHOOK

POST Webhook (webhooks adaptor)

PUT_WEBHOOK

Put Webhook (webhooks adaptor)

ASSIGN_USER_OF_SPECIFIC_TEAM

Assign To User Of A Specific Team (Service Request Provision adaptor)

ASSIGN_USER_OF_SPEC_USER_ROLE

Assign To User Of A Specific User Role (Service Request Provision adaptor)

FF_BY_USER_OF_SPEC_USER_ROLE

Fulfilled By User Of A Specific User Role (Service Request Provision adaptor)

FULFILLED_BY_SPECIFIC_USER

Fulfilled By Specific User (Service Request Provision adaptor)

PROV_ORDER_TO_SIMPHONY_POS

Provision Order To Simphony POS (MICROS Simphony Order Provision adaptor)

PROV_ORDER_TO_ALOHA_POS

Provision Order To Aloha POS (NCR Aloha Order Provision adaptor)

POST_PURCHASE
CANCEL_PURCHASE
adaptor_action_parameters
Array

Details about the adaptor’s actions parameters

Object
id
string GUID

The parameter identifier

Example:
4b8e0ae7-0f8a-4313-a1fd-ecc1c0510f55
parameter_key
string

The parameter key

Enumeration:
COMMUNICATION_PLAN
USERS_COMMUNICATE_USERS_ID
USERS_COMMUNICATE_USER_ROLE_ID
ASSIGN_ORDER_ORGANISATION_ID
ASSIGN_ORDER_USER_ID
FULFILL_ORDER_DISTANCE
FULFILL_ORDER_ORGANISATION_ID
FULFILL_ORDER_POSTAL_CODE
FULFILL_ORDER_POSTAL_CODE_RANGE
WEBHOOK
CUSTOMER_EVENT_CLASSIFICATION
WITHIN_ORGANISATIONS
parameter_from_value
string

The parameter from value

Example:
123
parameter_to_value
string

The parameter to value

Example:
1234
parameter_type
string

The parameter type

Enumeration:
DATE
INTEGER
NUMBER
STRING
parameter_group
string

The parameter group (used when more than one parameters should be specified for an adaptor’s action)

Example:
1
action_filters
Array

Details about the filters to be applied (required when type is based on Filter)

Object
filters
Array

Details about the applicable filtered attributes

Object
id
string GUID

The filter identiifer

Example:
edd5ac0e-05e3-e543-d38e-c6df6eed8d46
attribute
string

The attribute that its value will be compared based on the related operator

Enumeration:
SUPPLY_METHOD
PASS_CLASSIFICATION
REWARD_OFFER_GOAL
REWARD_OFFER_TYPE
REWARD_OFFER_SPEND_METHOD("
REWARD_OFFER_AWARD_AMOUNT("
REWARD_OFFER_AWARD_PERCENTAGE
ENTITY_CUSTOM_FIELD
CONACT_CUSTOM_FIELD
type
string

The type of the key

Enumeration:
STRING
INTEGER
NUMBER
DATE
operator
string

The filter operator to compare the attribute actual value with the filtered one

Enumeration:
EQUAL

Applicable for type of number/integer/date

IS

Applicable for type of string

EQUAL_GREATER

Applicable for type of number/integer/date

EQUAL_LESS

Applicable for type of number/integer/date

LESS

Applicable for type of number/integer/date

GREATER

Applicable for type of number/integer/date

value
string

The attribute value to apply the filter condition (either value or value_list should be specified)

Example:
123
value_list
Array of string

The supported list of values (either value or value_list should be specified)

custom_field_key
string

The custom field that its value will be compared based on the related operator

Example:
contact_rate
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/automations/6A24D2B5E44F44B28451FE021FCAD51E/actions HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "ACTIONB5E44F44B28451FE021FCAD51E",
            "order": 1,
            "adaptor": "COMMUNICATIONS",
            "adaptor_action": "REQUEST_APPROVAL",
            "adaptor_action_parameters": [
                {
                    "id": "4b8e0ae7-0f8a-4313-a1fd-ecc1c0510f55",
                    "parameter_key": "RICH_CONTENT",
                    "parameter_from_value": "123",
                    "parameter_to_value": "1234",
                    "parameter_type": "SUPPLY_METHOD",
                    "parameter_group": "1"
                }
            ],
            "action_filters": [
                {
                    "filters": [
                        {
                            "id": "edd5ac0e-05e3-e543-d38e-c6df6eed8d46",
                            "attribute": "NAME",
                            "type": "NUMBER",
                            "operator": "GREATER",
                            "value": "123",
                            "value_list": [
                                ""
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
Adaptor Action Records
POST /adaptors/{id}/actions/{action_id}/records/{record_id}
GET /adaptors/{id}/actions/{action_id}/records
GET /adaptors/{id}/actions/{action_id}/records/{record_id}
Update Action Records
POST /adaptors/{id}/actions/{action_id}/records/{record_id}

Change the value of a specific adaptor action record attribute

Path variables

id
string GUID required

The approval request (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
action_id
string GUID required

The action (identifier) whoe record will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFQ
record_id
string GUID required

The record (identifier) that will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFJ

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
key
string required

The record’s key

Example:
url-endpoint
value
string required

The record’s value

Example:
https://crm.com

Responses

200 200

Successful Request

Body
Object
id
string GUID

The record identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/adaptors/CAD1E31269B76D7A65ACCE45B2E68DFD/actions/CAD1E31269B76D7A65ACCE45B2E68DFQ/records/CAD1E31269B76D7A65ACCE45B2E68DFJ HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "key": "url-endpoint",
    "value": "https://crm.com"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Action Records
GET /adaptors/{id}/actions/{action_id}/records

Search for an adaptor action’s records (e.g. CRM.COM Apporvals Adaptor approval requests)

Path variables

id
string GUID required

The adaptor (identifier) whose actions will be retrieved

Example:
82697d43-4970-4dcc-bd35-7df27c72b8f6
action_id
string GUID required

The action (identifier) that will be retrieved

Example:
1b75a53f-b189-40bb-8db0-39b0578a6aqa

Request parameters

search_type
string optional

Defines the entitiy type that the search will be applied (required for search_value)

Enumeration:
KEY
LABEL
VALUE
ADAPTOR_NAME
ADAPTOR_ACTION_NAME
search_value
string optional

Defines the free text search parameter based on the provided type (required when search_type is specified)

Example:
POS Delivery
automations
array of string optional

Filter based on automations that triggered such action

Collection format: csv
Unique items: YES
adaptor_actions
array of string optional

Filter based on adapto action that created such record

Collection format: csv
Unique items: YES
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The record identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
record_attributes
Array

Details about the records attributes

Object
id
string GUID

The attribute identifier

Example:
CEEE83D6E0804A30966F684B0269AD9G
key
string

The record’s attribute key

Example:
url-endpoint
label
string

The record’s attribute label

Example:
URL Endpoint
type
string

The record’s attribute type

Example:
string
value
string

The record’s attribute value

Example:
https://crm.com
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/adaptors/82697d43-4970-4dcc-bd35-7df27c72b8f6/actions/1b75a53f-b189-40bb-8db0-39b0578a6aqa/records HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "record_attributes": [
                {
                    "id": "CEEE83D6E0804A30966F684B0269AD9G",
                    "key": "url-endpoint",
                    "label": "URL Endpoint",
                    "type": "string",
                    "value": "https://crm.com"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Action Record
GET /adaptors/{id}/actions/{action_id}/records/{record_id}

Retrieve details for a specifc adaptor action’s records (e.g. CRM.COM WEbhooks Adaptor webhook request)

Path variables

id
string GUID required

The adaptor (identifier) whose action’s record will be retrieved

Example:
82697d43-4970-4dcc-bd35-7df27c72b8f6
action_id
string GUID required

The action (identifier) whoe record will be retrieved

Example:
1b75a53f-b189-40bb-8db0-39b0578a6aqa
record_id
string GUID required

The record (identifier) that will be retrieved

Example:
1b75a53f-b189-40bb-8db0-39b0578a6a2w

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The record identifier

Example:
be8c05c4-2f97-4b40-a979-42f066db265c
record_attributes
Array

Details about the record attributes

Object
id
string GUID

The attribute identifier

Example:
be8c05c4-2f97-4b40-a979-42f066db26qw
key
string

The record’s attribute key

Example:
url-endpoint
label
string

The record’s attribute label

Example:
URL Endpoint
type
string

The record’s attribute type

Example:
string
value
string

The record’s attribute value

Example:
https://crm.com
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/adaptors/82697d43-4970-4dcc-bd35-7df27c72b8f6/actions/1b75a53f-b189-40bb-8db0-39b0578a6aqa/records/1b75a53f-b189-40bb-8db0-39b0578a6a2w HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "be8c05c4-2f97-4b40-a979-42f066db265c",
    "record_attributes": [
        {
            "id": "be8c05c4-2f97-4b40-a979-42f066db26qw",
            "key": "url-endpoint",
            "label": "URL Endpoint",
            "type": "string",
            "value": "https://crm.com"
        }
    ]
}
Approvals
GET /approval_requests
POST /approval_requests/{id}/actions
GET /approval_requests/my_pending_approvals
GET /approval_requests/my_requests
List Approval Requests
GET /approval_requests

Search for approval requests

Request parameters

search_value
string optional

The value of the search (case insensitive) across entity and entity reference

Example:
Bravo Brewery
state
string optional

Filter based on approval request state

Enumeration:
PENDING
APPROVED
REJECTED
automations
array of string optional

Filter based on automations that triggered such request (applicable only when org_requests is set to NETWORK_REQUESTS)

Collection format: csv
Unique items: YES
user_id
string GUID optional

Filter based on a single user that is authorised to approve/reject such request

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
contact_id
string GUID optional

Filter based on a single contact that is authorised to approve/reject such request

Example:
58c4a0c4-f60b-9930-c8da-89e9949a7850
authorised_type
string optional

Filter based on the condition type that are authorised to approve/reject such requests

Enumeration:
TEAM
USER
CONTACT
requested_by
string GUID optional

Filter based on the entity (contact/user) that requested such approval

Example:
b5582bc8-41ec-9c97-7446-2944e60b3ff8
entity_type
string optional

Filter based on the entity type that such requests are applied to

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
entity
string GUID optional

Filter based on entity record that such request is applied to

Example:
eebefada-399d-e892-0a20-d7963e9db19a
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The approval request identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
state
string

The approval request state

Enumeration:
PENDING
APPROVED
REJECTED
entity
Object

Details about the entity that such approval request was applied to

id
string GUID

The entity identifier

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
type
string

The approval entity type

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
reference
string

The entity reference name/code/number

Example:
CO1234
automations
Object

Details about the automation

id
string GUID

The automation identifer

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
name
string

The automation name

Example:
Request approval on newly activated offers
responses
Array

Details about the approval request’s response

Object
message
string

The authorised user/contact response message on this request

Example:
This is a response message
state
string

The resposne state

Enumeration:
APPROVED
REJECTED
authorised_by
Object

Details about the person (user/contact) who approved/rejected such request

id
string GUID

The authorised person identifier

Example:
23490b97-dd93-3eb4-c3bc-e6828e12e2c1
name
string

The authorised person full name

Example:
John Doe
type
string

The authorised type of person

Enumeration:
CONTACT
USER
authorised_on
integer GUID

The date/time when such request was approvded/rejected

Example:
1611930210
authorised_conditions
Array

Details about the authorised by type who can approve/reject such requests

Object
id
string GUID

The authorised condition identifier

Example:
18eb40c8-ba71-fa51-9de7-5b7017962ccf
name
string

The authorised condition name (e.g. contact full name, user role name)

Example:
Support
type
string

The authorised condition type

Enumeration:
TEAM
USER
CONTACT
created_date
integer

The date that the approval was requested

Example:
1642508197
pending_requests
integer

Defines how many should approve/reject the approval

Example:
2
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/approval_requests HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "state": "APPROVED",
            "description": "The award of the offer has been changed to 100% from what it was 50%",
            "response": "Approved",
            "authorised_by": {
                "id": "23490b97-dd93-3eb4-c3bc-e6828e12e2c1",
                "name": "John Doe",
                "type": "USER"
            },
            "authorised_on": 1611930210,
            "automations": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "name": "Request approval on newly activated offers"
            },
            "entity": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "type": "REWARD_OFFER",
                "reference": "5% discount"
            },
            "authorised_conditions": [
                {
                    "id": "18eb40c8-ba71-fa51-9de7-5b7017962ccf",
                    "name": "John Doe",
                    "type": "USER"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Perform Approval Request Actions
POST /approval_requests/{id}/actions

Change the life cycle state of a single approval request

Path variables

id
string GUID required

The approval request identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string required

The approval request state that will be changed to

Enumeration:
APPROVED
REJECTED
response
string nullable

The reason why the approval request was approved or rejected

Example:
Award cannot be 100%

Responses

200 200

Successful Request

Body
Object
id
string GUID

The approval request identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/approval_requests/CAD1E31269B76D7A65ACCE45B2E68DFD/life_cycle_state HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "REJECTED"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Pending Approval Requests - My Approvals
GET /approval_requests/my_pending_approvals

Retrieve the pending approvals that the signed-in user is authorised to approve/reject, but not yet process them

Request parameters

search_value
string optional

The value of the search (case insensitive) across entity and entity reference

Example:
Bravo Brewery
entity_type
string optional

Filter based on the entity type that such requests are applied to

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The approval request identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
entity
Object

Details about the entity that such approval request was applied to

id
string GUID

The entity identifier

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
type
string

The approval entity type

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
reference
string

The entity reference name/code/number

Example:
CO1234
automations
Object

Details about the automation

id
string GUID

The automation identifer

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
name
string

The automation name

Example:
Request approval on newly activated offers
created_date
integer

The date that the approval was requested

Example:
1642508197
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/approval_requests/my_pending_approvals HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "entity": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "type": "SERVICE_REQUEST",
                "reference": "CO1234"
            },
            "automations": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "name": "Request approval on newly activated offers"
            },
            "created_date": 1642508197
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
List Approval Requests - My Requested Approvals
GET /approval_requests/my_requests

Retrieve the approvals requested by the signed-in user

Request parameters

search_value
string optional

The value of the search (case insensitive) across entity and entity reference

Example:
Bravo Brewery
state
string optional

Filter based on approval request state

Enumeration:
PENDING
APPROVED
REJECTED
entity_type
string optional

Filter based on the entity type that such requests are applied to

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The approval request identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
state
string

The approval request state

Enumeration:
PENDING
APPROVED
REJECTED
entity
Object

Details about the entity that such approval request was applied to

id
string GUID

The entity identifier

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
type
string

The approval entity type

Enumeration:
ORGANISATION
REWARD_OFFER
ORDER
SERVICE_REQUEST
reference
string

The entity reference name/code/number

Example:
CO1234
automations
Object

Details about the automation

id
string GUID

The automation identifer

Example:
cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0
name
string

The automation name

Example:
Request approval on newly activated offers
responses
Array

Details about the approval request’s response

Object
message
string

The authorised user/contact response message on this request

Example:
This is a response message
state
string

The resposne state

Enumeration:
APPROVED
REJECTED
authorised_by
Object

Details about the person (user/contact) who approved/rejected such request

id
string GUID

The authorised person identifier

Example:
23490b97-dd93-3eb4-c3bc-e6828e12e2c1
name
string

The authorised person full name

Example:
John Doe
type
string

The authorised type of person

Enumeration:
CONTACT
USER
authorised_on
integer GUID

The date/time when such request was approvded/rejected

Example:
1611930210
created_date
integer

The date that the approval was requested

Example:
1642508197
pending_requests
integer

Defines how many should approve/reject the approval

Example:
2
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/approval_requests/my_requests HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "state": "APPROVED",
            "entity": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "type": "ORDER",
                "reference": "CO1234"
            },
            "automations": {
                "id": "cf010c72-a2cb-48f8-a9fa-1ed99c8d6ec0",
                "name": "Request approval on newly activated offers"
            },
            "responses": [
                {
                    "message": "This is a response message",
                    "state": "APPROVED",
                    "authorised_by": {
                        "id": "23490b97-dd93-3eb4-c3bc-e6828e12e2c1",
                        "name": "John Doe",
                        "type": "USER"
                    },
                    "authorised_on": 1611930210
                }
            ],
            "created_date": 1642508197,
            "pending_requests": 2
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Webhooks
POST /webhooks
PUT /webhooks/{id}
DELETE /webhooks/{id}
GET /webhooks
GET /webhooks/{id}
GET /webhook_requests
POST /resend_webhook_requests
Create Webhook
POST /webhooks

Create a new webhook

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The webhook name

Example:
CRMdotCOM Delivery
method
string required

The webhook method type

Enumeration:
POST
PUT
url_endpoint
string required

The webhook url endpoint

Example:
https://crm.com/delivery
url_auth
string nullable

Defines how the webhook will be protected

Enumeration:
NO_AUTH
USERNAME_PASSWORD
API_KEY
Default:
NO_AUTH
username
string nullable

The username that will auth the webhook requests (applicable if url_auth = USERNAME_PASSWORD)

Example:
johndoe
password
string nullable

The password that will auth the webhook requests (applicable if url_auth = USERNAME_PASSWORD)

Example:
crm.com
api_key
string nullable

The api key that will auth the webhook requests (applicable if url_auth = API_KEY)

Example:
qwert-12345-qwewerwer-123234234-werwerwr
retry_count
integer nullable

Number of times to retry

Example:
1
retry_after
integer nullable

Wait for period before retry (in seconds)

Example:
60

Responses

200 200

OK

Body
Object
id
string GUID

The webhook identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/webhooks HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "CRMdotCOM Delivery",
    "method": "POST",
    "url_endpoint": "https://crm.com/delivery",
    "url_auth": "NO_AUTH",
    "username": "johndoe",
    "password": "crm.com",
    "api_key": "qwert-12345-qwewerwer-123234234-werwerwr"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD"
}
Update Webhook
PUT /webhooks/{id}

Update an existing webhook

Path variables

id
string required

The webhook (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68WHI

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The webhook name

Example:
CRMdotCOM Delivery
url_endpoint
string nullable

The webhook url endpoint

Example:
https://crm.com/delivery
url_auth
string nullable

Defines how the webhook will be protected

Enumeration:
NO_AUTH
USERNAME_PASSWORD
API_KEY
Default:
NO_AUTH
username
string nullable

The username that will auth the webhook requests (applicable if url_auth = USERNAME_PASSWORD)

Example:
johndoe
password
string nullable

The password that will auth the webhook requests (applicable if url_auth = USERNAME_PASSWORD)

Example:
crm.com
api_key
string nullable

The api key that will auth the webhook requests (applicable if url_auth = API_KEY)

Example:
qwert-12345-qwewerwer-123234234-werwerwr
retry_count
integer nullable

Number of Times to Retry

Example:
1
retry_after
string nullable

Wait for period before retry (in seconds)

Example:
60

Responses

200 200

OK

Body
Object
id
string GUID

The webhook identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/webhooks/CAD1E31269B76D7A65ACCE45B2E68WHI HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "CRMdotCOM Delivery",
    "url_endpoint": "https://crm.com/delivery",
    "url_auth": "NO_AUTH",
    "username": "johndoe",
    "password": "crm.com",
    "api_key": "qwert-12345-qwewerwer-123234234-werwerwr"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Webhook
DELETE /webhooks/{id}

Delete an existing webhook

Path variables

id
string required

The webhook (identifier) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68WHI

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/webhooks/CAD1E31269B76D7A65ACCE45B2E68WHI HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Webhooks
GET /webhooks

Retrieve all webhooks

Request parameters

search_value
string optional

The value of the search (case insensitive) across Name, URL Endpoint

Example:
https://crm.com/delivery
name
string optional

Filter based on the name

Example:
CRMdotCOM Delivery
url_endpoint
string optional

Filter based on the url endpoint

Example:
https://crm.com/delivery
automation_entity
string optional

Filter based on related automation entity

Example:
ORDERS
automation_event
string optional

Filter based on related automation event

Example:
NEW_PURCHASE
has_failed_requests
boolean optional

Filter based on whether webhook has at least one failed request

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation’ webhooks

Object
id
string GUID

The webhook identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The webhook name

Example:
Registration Name
method
string

The webhook method type

Enumeration:
POST
PUT
url_endpoint
string

The webhook url endpoint

Example:
https;//crm.com/delivery
url_auth
string

Defines how the webhook will be protected

Enumeration:
NO_AUTH
USERNAME_PASSWORD
API_KEY
Default:
NO_AUTH
number_requests
Object
pending
string

The number of pending requests

Example:
12
successful
string

The number of successful requests

Example:
2
failed
string

The number of failed requests

Example:
1
retry_count
integer

Number of times to retry

Example:
1
retry_after
integer

Wait for period before retry

Example:
60
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/webhooks HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Registration Name",
            "url_endpoint": "https;//crm.com/delivery",
            "url_auth": "API_KEY"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Webhook
GET /webhooks/{id}

Get details of a single webhook

Path variables

id
string GUID required

The webhooks (identifier) that will be retrieved

Example:
API1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation’ webhooks

Object
id
string GUID

The organisation’s webhook identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The webhook name

Example:
CRMdotCOM Delivery
method
string

The webhook method type

Enumeration:
POST
PUT
url_endpoint
string

The webhook url endpoint

Example:
https://crm.com/delivery
url_auth
string

Defines how the webhook will be protected

Enumeration:
NO_AUTH
USERNAME_PASSWORD
API_KEY
Default:
NO_AUTH
username
string

The webhook auth username (applicable only if url_auth = USERNAME_PASSWORD)

Example:
johndoe
password
string

The webhook auth password (applicable only if url_auth = USERNAME_PASSWORD)

Example:
crm.com
api_key
string

Defines the date up until the secret api key will be active

Example:
sdfsdfsdf-32423423423-wefsdfsdfdsf-234234234
number_requests
Object
pending
integer

The number of pending requests

Example:
12
successful
integer

The number of successfull requests

Example:
2
failed
integer

The number of failed requests

Example:
1
retry_count
integer

Number of times to retry

Example:
1
retry_after
integer

Wait for period before retry (in seconds)

Example:
60
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/webhooks/API1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "CRMdotCOM Delivery",
            "url_endpoint": "https://crm.com/delivery",
            "url_auth": "USERNAME_PASSWORD",
            "username": "johndoe",
            "password": "crm.com",
            "api_key": "sdfsdfsdf-32423423423-wefsdfsdfdsf-234234234"
        }
    ]
}
List Webhook Requests
GET /webhook_requests

Retrieve webhook requests

Request parameters

search_value
string optional

The value of the search (case insensitive) across Webhook Name, URL Endpoint

Example:
https://crm.com/delivery
webhooks
array of string optional

Filter based on the webhook

Collection format: csv
Unique items: YES
url_endpoint
string optional

Filter based on the url endpoint

Example:
https://crm.com/delivery
state
string optional

Filter based on the request state

Enumeration:
PENDING
SUCCESS
FAILED
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation’ webhook requests

Object
id
string GUID

The webhook request identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
state
string

The state of the webhook request

Enumeration:
PENDING
SUCCESS
FAILED
url_endpoint
string

The webhook url endpoint

Example:
https;//crm.com/delivery
url_auth
string

Defines how the webhook will be protected

Enumeration:
NO_AUTH
USERNAME_PASSWORD
API_KEY
Default:
NO_AUTH
body
string

The request body that was sent

Example:
POST /crm.com/delivery HTTP/1.1 Host: staging.crm.com Content-Type: application/json api_key: 123456789012-1234-1234-1234-123456789012 Content-Type: text/plain { "contact_id": "123456789012-ABCD-ABCD-ABCD-123456789012", "amount": 20.45 }
response
string

The response that was sent

Example:
{ "status": { "code": "COM.CRM.EXCEPTION.INVALIDTOKENEXCEPTION", "description": "The specific token is not valid.", "message": "The token is invalid, please obtain a new one." } }
retries
integer

The total number of request retries

Example:
3
webhook
Object

The webhook of the request

id
string

The webhook identifier

Example:
API1E31269B76D7A65ACCE45B2E68WIH
name
string

The webhook name

Example:
CRMdotCOM Delivery
automation
Object

The automation that triggered the webhook

id
string

The automation identifier

Example:
b63ed1ab-0256-453d-82a4-a8a83a02ea8b
name
string

The automation name

Example:
Share content to delivery system
entity
Object

Information about the related entity that the request is created for

type
string

The entity type that the webhook request is created for

Examples:
CONTACTORDERREWARDOFFER
reference
string

The entity’s reference name/code/number

Example:
ORD1234ER
date
integer epoch

The date that such request was made

Example:
1596093272
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/webhook_requests HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "state": "SUCCESS",
            "url_endpoint": "https;//crm.com/delivery",
            "url_auth": "USERNAME_PASSWORD",
            "body": "POST /crm.com/delivery HTTP/1.1 Host: staging.crm.com Content-Type: application/json api_key: 123456789012-1234-1234-1234-123456789012 Content-Type: text/plain  {     \"contact_id\": \"123456789012-ABCD-ABCD-ABCD-123456789012\",     \"amount\": 20.45 }",
            "response": "{     \"status\": {         \"code\": \"COM.CRM.EXCEPTION.INVALIDTOKENEXCEPTION\",         \"description\": \"The specific token is not valid.\",         \"message\": \"The token is invalid, please obtain a new one.\"     } }",
            "retries": 3,
            "webhook": {
                "id": "API1E31269B76D7A65ACCE45B2E68WIH",
                "name": "CRMdotCOM Delivery"
            },
            "automation": {
                "id": "b63ed1ab-0256-453d-82a4-a8a83a02ea8b",
                "name": "Share content to delivery system"
            },
            "entity": {
                "type": "CONTACT",
                "reference": "ORD1234ER"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Replay Webhook
POST /resend_webhook_requests

Resend a number of failed webhook requests

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
webhooks
Array

List all failed webhook requests that should be resend

string GUID
Example:
a87901a4-6885-af33-5de8-8748b3f615ca

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Bulk Data Operations
Import Data
GET /imports/preview
POST /imports
GET /imports
POST /imports/{id}/actions
Import Preview
GET /imports/preview

Preview the content of a file that will be imported

Notes

IMPORT DATA FLOW

Importing Data should be made based on the following API order

  1. Upload File Signature
  2. Optionally, preview the content of the uploaded file via Import Preview
  3. Submit a request to import the content of the uploaded file, including a couple behavorial options via Import Data

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required

The file (identiifer) that will be previewed

Example:
f56f9cd8-9cb2-bbe6-d4d9-ae14bb1f0399
preview_rows
integer nullable

Defines the number of rows that will be previewed (header row is excluded)

Default:
10
Example:
5
exclude_header
boolean required

Defines whether the header row values will be excluded from import or not

Example:
false
data_mapping
Array required

Defines the mapping between the imported file attribures and system attributes

Object
import_key
string required

The imported file attribute that will be mapped to the system’s one

Example:
contact first name
attribute_key
string required

The system attribute that will be mapped to the imported file’s one

Example:
first_name
is_custom
boolean required

Defines whether the system attribute key is a custom one or not

Example:
false

Responses

200 OK
Body
Object
content
Array

Details about the file preview per row

Object
header
string

The header attribute of the specific row

Example:
Organisation Name
values
Array

The previewed values of the specific row

Example:
[
    "CRM", "CRMI"
]
string
Example:
CRM
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/imports/preview HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "file_id": "f56f9cd8-9cb2-bbe6-d4d9-ae14bb1f0399",
    "preview_rows": 2
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "header": "Organisation Name",
            "values": [
                "CRM", "CRMI"
            ]
        },
        {
            "header": "Organisation Type",
            "values": [
                "BUSINESS", "VENUE"
            ]
        }
    ]
}
Import Data
POST /imports

Submit a request for importing data along with processing options

Notes

IMPORT DATA FLOW

Importing Data should be made based on the following API order

  1. Upload File Signature
  2. Optionally, preview the content of the uploaded file via Import Preview
  3. Submit a request to import the content of the uploaded file, including a couple behavorial options via Import Data

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required

The file (identifier) that will be used for importing data

Example:
1e347d4d-ab96-6957-fdb6-35e72b3d9185
type
string required

The type of the entity that data will be imported

Enumeration:
CONTACTS
DEVICES
PRODUCTS
exclude_header
boolean nullable

Defines whether the header row values will be excluded from import or not

Default:
true
Example:
true
update_data
boolean nullable

Defines whether existing records will be updated or not

Default:
false
Example:
false
auto_generate_config
boolean nullable

Defines whether missing attributes will be created automatically

Default:
false
Example:
true
data_mapping
Array required

Defines the mapping between the imported file attribures and system attributes

Object
import_key
string required

The imported file attribute that will be mapped to the system’s one

Example:
contact first name
attribute_key
string required

The system attribute that will be mapped to the imported file’s one

Example:
first_name
is_custom
boolean required

Defines whether the system attribute key is a custom one or not

Example:
false

Responses

200 OK
Body
Object
id
string GUID

The import definition identifier

Example:
1e347d4d-ab96-6957-fdb6-35e72b3d9185
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/imports HTTP/1.1 

Content-Type: application/json

{
    "file_id": "1e347d4d-ab96-6957-fdb6-35e72b3d9185",
    "type": "CONTACTS",
    "exclude_header": true,
    "update_data": "false",
    "auto_generate_config": true,
    "data_mapping": [
        {
            "import_key": "contact first name",
            "attribute_key": "first_name",
            "is_custom": "false"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "1e347d4d-ab96-6957-fdb6-35e72b3d9185"
}
List Imports
GET /imports

Search for import data definitions

Request parameters

status
string optional

Filter imports based on status

Enumeration:
PENDING
IN_PROGRESS
COMPLETED
FAILED
type
string optional

Filter imports based on imported record type

Enumeration:
CONTACTS
DEVICES
PRODUCTS
imported_on
string optional

Filter based on the imported date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. imported_on[gte]=1618395497&imported_on[lt]=1618395497).

Enumeration:
imported_on[gt]

Returns results where the imported date is greater than this value

imported_on[gte]

Returns results where the imported date is greater than or equal to this value

imported_on[lt]

Returns results where the imported date is less than this value

imported_on[lte]

Returns results where the imported date is less then or equal to this value

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The import definition identifier

Example:
507c17d2-3976-d1e5-ccf5-cf3c1334acc7
status
string

The export definition status

Enumeration:
PENDING
IN_PROGRESS
COMPLETED
FAILED
type
string

The type of the entity that data will be imported

Enumeration:
CONTACTS
DEVICES
PRODUCTS
imported_on
integer epoch

The date that such import was made

Example:
1623677135
options
Object

Details how the import file content will be processed

exclude_header
boolean

Defines whether the header row values will be excluded from import or not

Example:
true
update_data
boolean

Defines whether existing records will be updated or not

Example:
true
auto_generate_config
boolean

Defines whether missing attributes will be created automatically

Example:
false
file
Object

Details about the uploaded file that was used for import

id
string GUID

The file identifier

Example:
507c17d2-3976-d1e5-ccf5-cf3c1334acc7
name
string

The file name

Example:
contacts.csv
error_file
Object

Details about the file that contain all failed imported data

id
string GUID

The file identifier

Example:
507c17d2-3976-d1e5-ccf5-cf3c1334acc7
name
string

The file name

Example:
contacts_errors.csv
processed_results
Object

Details about the processed data

new
integer

The records that were created successfully

Example:
19
updated
integer

The records that were updated successfully

Example:
4
unchanged
integer

The records that were not changed

Example:
4
errors
integer

The records that were failed to be processed

Example:
1
total
integer

The total number of records that were imported

Example:
28
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/imports HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "507c17d2-3976-d1e5-ccf5-cf3c1334acc7",
            "status": "COMPLETED",
            "type": "PRODUCTS",
            "imported_on": 1623677135,
            "options": {
                "exclude_header": true,
                "update_data": true,
                "auto_generate_config": "false"
            },
            "file": {
                "id": "507c17d2-3976-d1e5-ccf5-cf3c1334acc7",
                "name": "contacts.csv"
            },
            "error_file": {
                "id": "507c17d2-3976-d1e5-ccf5-cf3c1334acc7",
                "name": "contacts_errors.csv"
            },
            "processed_results": {
                "new": 19,
                "updated": 4,
                "unchanged": 4,
                "errors": 1,
                "total": 28
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Import Actions
POST /imports/{id}/actions

Apply an action on an existing import definition

Path variables

id
string GUID required

The import definition (identifier) on which an action will be performed

Example:
0e2e1e37-b118-7bbc-db46-6cd954e01a89

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The type of action that will be performed

Enumeration:
REPLAY

Re-submit an import with FAILED status

Responses

200 OK
Body
Object
id
string GUID

The import definition identifier

Example:
0e2e1e37-b118-7bbc-db46-6cd954e01a89
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/imports/0e2e1e37-b118-7bbc-db46-6cd954e01a89/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "REPLAY"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0e2e1e37-b118-7bbc-db46-6cd954e01a89"
}
Business Network
POST /organisations/register
POST /organisations/{id}/network
PUT /organisations/{id}
DELETE /organisations/{id}
GET /organisations/{id}/network
GET /organisations/{id}
GET /organisations/{id}/activity_feed
POST /organisations/{id}/switch
POST /organisations/{id}/masquerade
POST /organisations/{id}/actions
POST /organisations/{id}/media_groups
POST /organisations/import
GET /organisations/{id}/billing
Register Organisation
POST /organisations/register

Creates a business semantic parent as the primary business.

Request headers

api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
name
string required

The name of the organisation

Example:
Delicious Food Group
description
string nullable

A brief description of the organisation

Example:
Lorem Ipsum
org_type
string required

The type of the organisation

Enumeration:
BUSINESS
MERCHANT
SERVICE_PROVIDER
is_business
boolean required

Defines whether the organisation is the primary business of the business network

Example:
true
organisation_id
string GUID required

The parent organisation identifier that this organisation belongs to

Example:
4bd55b60-2c2a-d588-7a94-0890ced7e0ba
test_mode
boolean nullable

Determines whether the organisation record will be used for test purposes

Example:
false
is_sandbox_on
boolean nullable

Determines whether the sandbox mode is enabled or not

Example:
true
owner
Object required

Information about the owner (admin user) of the organisation

first_name
string required

The user’s first name

Example:
John
last_name
string required

The user’s last name

Example:
Doe
identity
Object nullable

Information about the owner’s identity

provider
string

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string required

The identity’s challenge

Example:
jd@crm.com
identity_value
string nullable

The identity’s value (e.g. password)

Example:
12345
contact_info
Array required

Information about the owner’s contact information

Object
name
string nullable

The name of the contact information

type
string

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string required

The contact information value

Example:
4499885544
country_code
string nullable

The country code of the related contact info of type phone

Example:
CYP
location
Array nullable

Information about the organisation’s location

Object

Information about the organisation’s location

name
string nullable

The name of the location

Example:
Head Office
address_line_1
string required

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string nullable

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string nullable

The state/province/county of the location

Example:
Egkomi
town_city
string required

The town/city of the location

Example:
Nicosia
postal_code
string required

The postal code of the location

Example:
2415
country_code
string required

The country code of the location

Example:
CY
care_of
string nullable

The care of information of the location

Example:
c/o Company
lat
number nullable

The latitude of the location

Example:
35.157115
lon
number nullable

The longitude of the location

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
currency_code
string nullable

The organisation’s base currency (applicable for service owner/business)

Default:
EUR
Example:
EUR
timezone
string nullable

The organisation timezone (applicable for business)

Example:
EUROPE/ATHENS
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

OK

Body
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/register HTTP/1.1 

Content-Type: application/json
api_key: 8c54d563-b991-4b76-8a83-557c08166f95

{
    "name": "Delicious Food Group",
    "description": "Lorem Ipsum",
    "vat_number": "VAT123456789",
    "org_type": "BUSINESS",
    "is_business": "true",
    "organisation_id": "11",
    "test_mode": "false",
    "is_sandbox_on": "true",
    "owner": {
        "first_name": "John",
        "last_name": "Doe",
        "contact_info": [
            {
                "name": "",
                "type": "EMAIL",
                "value": "4499885544"
            }
        ]
    },
    "location": [
        {
            "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",
            "care_of": "",
            "lat": "35.157115",
            "lon": "33.313719",
            "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Expand Business Network
POST /organisations/{id}/network

Expand the business network with new organisations such as transaction processor, service owners and business

Path variables

id
string GUID required

The organisation (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
org_type
string required

The type of the new organisation

Enumeration:
TRANSACTION_PROCESSOR

Applicable on the level of a Cloud Operator

SERVICE_OWNER

Applicable on the level of a Cloud Operator

BUSINESS

Applicable on the level of a Service Owner

MERCHANT

Applicable on the level of a Business

VENUE

Applicable on the level of a Business or Merchant

name
string required

The name of the organisation

Example:
Delicious Food Group
description
string nullable

A brief description of the organisation

Example:
Lorem Ipsum
is_business
boolean required

Defines whether the organisation is the primary business of the network

Example:
true
country_agreement
string nullable

The organisation’s country of agreement code (applicable for service owner/business)

Example:
CYP
industry_id
string GUID nullable

The organisation industry identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
industry_sectors
Array nullable

The organisation industry sectors

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
groups
Array nullable

The groups of the organisation (only organisation types of Merchant, Venue and Service Point can be grouped)

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
owner
Object required

Information about the owner (admin user) of the organisation

first_name
string required

The user’s first name

Example:
John
last_name
string required

The user’s last name

Example:
Doe
identity
Object nullable

Information about the owner’s identity

provider
string

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string required

The identity’s challenge

Example:
jd@crm.com
identity_value
string nullable

The identity’s value (e.g. password)

Example:
12345
contact_info
Array required

Information about the owner’s contact information

Object
name
string nullable

The name of the contact information

type
string

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string required

The contact information value

Example:
4499885544
country_code
string nullable

The country code of the related contact info of type phone

Example:
CYP
contact_info
Array nullable

Information about the organisation’s contact details

Unique items: YES
Object

Information about the owner (admin user) of the organisation

name
string nullable

The name of the contact information

Example:
Main Office
type
string

The type of the organisation’s contact detail

Enumeration:
EMAIL
PHONE
value
string required

The contact information value

Example:
johndoe@deliciousfood.com
country_code
string nullable

The country code of the related contact detail of type phone

Example:
CYP
locations
Array nullable

Information about the organisation’s location

Unique items: YES
Object

Information about the organisation’s location

name
string nullable

The name of the location

Example:
Head Office
address_line_1
string required

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string nullable

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string nullable

The state/province/county of the location

Example:
Egkomi
town_city
string required

The town/city of the location

Example:
Nicosia
postal_code
string required

The postal code of the location

Example:
2415
country_code
string required

The country code of the location

Example:
CY
care_of
string nullable

The care of information of the location

Example:
c/o Company
lat
number nullable

The latitude of the location

Example:
35.157115
lon
number nullable

The longitude of the location

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
taps
Array nullable

Information about the organisation’s transaction acquiring points

Unique items: YES
Object

Information about the organisation’s external references

name
string required

The transaction acquiring point name

Example:
POS
code
string nullable

The transaction acquiring point code

Example:
02451
is_active
boolean nullable

Defines whether the transaction acquiring point is active or not

Default:
true
Example:
true
description
string nullable

The transaction acquiring point description

Example:
pos system
external_ip
string nullable

IP address of External Device

Example:
82.102.93.164
external_port
string nullable

Port of the External IP

Example:
9100
tap_type
string required

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
string nullable

Optional specification of external reference

Enumeration:
JCC
TWINSOFT
ALOHA
WIFI_PLATFORM
business_activities
Array nullable

The organisation business activities

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
inherit_from_parent
boolean nullable

Defines whether the new organisation will have the same industry, industry sectors and business activities as its parent organisation

Example:
false
organisation_profile
Object nullable

Details about the organisation profile

registration_number
string nullable

The organisation’s registration number

Example:
1234
tax_reference_number
string nullable

The organisation’s TAX reference number

Example:
TAX1234
vat_reference_number
string nullable

The organisation’s VAT reference number

Example:
VAT1234
registration_country
string nullable

The company’s registration country code

Example:
CYP
organisation_id
string GUID required

The parent organisation identifier that this organisation belongs to

Example:
e7251be4-89f2-8cea-7a4a-65b679cf6131
cloud_name
string required nullable

The name that the organisation will have on the cloud (applicable for Service Owner organisations; special characters not allowed)

Example:
crmdotcom
organisation_tags
Array nullable

The tags of the organisation

string
Example:
Accounting
service_organisations
Array GUID nullable

The organisations (service owners) that the organisation (transaction processor) serves

Unique items: YES
Example:
7c56cc02-48cf-9832-e412-a4ae022cd547
string GUID
Example:
7c56cc02-48cf-9832-e412-a4ae022cd547
contact_registry
boolean nullable

Defins whether organisation will support contact registry or not (applicable for Service Owner, Business, Subsidiary)

Example:
true
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
wifi_platform
Object nullable

Details about provisioning an organisation over to WiFi

integration_id
string GUID required

The integration identifier that organisation will be provisioned for WiFi

Example:
88165da9-58a9-74cd-3da5-593b901fc0ec
site_id
string required

The site identifier that will be used to identify the organisation over to WiFi platform

Example:
88quh2m6

Responses

200 200

OK

Body
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/network HTTP/1.1 

Content-Type: application/json

{
    "org_type": "VENUE",
    "name": "Delicious Food Group",
    "description": "Lorem Ipsum",
    "is_business": "true",
    "country_agreement": "CYP",
    "industry_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "industry_sectors": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "groups": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "owner": {
        "first_name": "John",
        "last_name": "Doe",
        "identity": {
            "provider": "EMAIL",
            "identity_challenge": "jd@crm.com",
            "identity_value": "12345"
        },
        "contact_info": [
            {
                "name": "",
                "type": "EXTENSION",
                "value": "4499885544",
                "country_code": "CYP"
            }
        ]
    },
    "contact_info": [
        {
            "name": "Main Office",
            "type": "EMAIL",
            "value": "johndoe@deliciousfood.com",
            "country_code": "CYP"
        }
    ],
    "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",
            "care_of": "c/o Company",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    ],
    "taps": [
        {
            "name": "POS",
            "code": "02451",
            "is_active": "true",
            "description": "pos system",
            "external_ip": "82.102.93.164",
            "external_port": "9100",
            "tap_type": "CARD_TERMINAL",
            "external_type": "ALOHA"
        }
    ],
    "business_activities": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "inherit_from_parent": "false",
    "organisation_profile": {
        "registration_number": "1234",
        "tax_reference_number": "TAX1234",
        "vat_reference_number": "VAT1234",
        "registration_country": "CYP"
    },
    "organisation_id": "e7251be4-89f2-8cea-7a4a-65b679cf6131",
    "cloud_name": "crmdotcom",
    "organisation_tags": [
        "Accounting"
    ],
    "service_organisations": [
        "7c56cc02-48cf-9832-e412-a4ae022cd547"
    ],
    "contact_registry": "true",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "wifi_platform": {
        "integration_id": "88165da9-58a9-74cd-3da5-593b901fc0ec",
        "site_id": "88quh2m6"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Organisation
PUT /organisations/{id}

Update a single organisation

Path variables

id
string GUID required

The organisation (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
name
string nullable

The name of the organisation

Example:
Delicious Food Group
description
string nullable

A brief description of the organisation

Example:
Lorem Ipsum
contact_info
Array nullable

Information about the organisation’s contact details

Unique items: YES
Object
id
string GUID required nullable

The identifier of the organisation’s contact detail

Example:
CK1234567890123456789012345678
type
string

The type of the organisation’s contact detail

Enumeration:
EMAIL
PHONE
value
string required

The value of the organisation’s contact detail

Example:
info@crm.com
name
string nullable

The name of the organisation’s contact detail

Example:
Head Office
industry_id
string GUID nullable

The industry of the organisation

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
industry_sectors
Array nullable

The industry sectors of the organisation

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
business_activities
Array nullable

The business activities of the organisation

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
groups
Array nullable

The groups of the organisation (only organisation types of Merchant, Venue and Service Point can be grouped)

Unique items: YES
string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
inherit_from_parent
boolean nullable

Defines whether the new organisation will have the same industry, industry sectors, business activities and reward tags as its parent organisation

Example:
false
organisation_profile
Object nullable

Details about the organisation profile

registration_number
string

The organisation’s registration number

Example:
1234
tax_reference_number
string

The organisation’s TAX reference number

Example:
TAX1234
vat_reference_number
string

The organisation’s VAT reference number

Example:
VAT1234
registration_country
string

The company’s registrationc country code

Example:
CYP
cloud_name
string nullable

The name that the organisation will have on the cloud (applicable for Service Owner organisations; special characters not allowed)

Example:
crmdotcom
organisation_tags
Array nullable

The tags of the organisation

string
Example:
Accounting
service_organisations
Array GUID nullable

The organisations (service owners) that the organisation (transaction processor) serves

Unique items: YES
Example:
1daf80b1-134b-36eb-7146-76dec04e6c5d
string GUID
Example:
1daf80b1-134b-36eb-7146-76dec04e6c5d
contact_registry
boolean nullable

Defines whether organisation supports contact registry or not

Example:
true
locations
Object nullable

Information about the organisation’s location

id
string GUID nullable

The location identifier that will be updated

Example:
a6cc4f88-cab1-4ab2-98d3-4655789277e2
name
string nullable

The name of the location

Example:
Head Office
address_line_1
string required

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string nullable

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string nullable

The state/province/county of the location

Example:
Egkomi
town_city
string required

The town/city of the location

Example:
Nicosia
postal_code
string required

The postal code of the location

Example:
2415
country_code
string required

The country code of the location

Example:
CY
care_of
string nullable

The care of information of the location

lat
number nullable

The latitude of the location

Example:
35.157115
lon
number nullable

The longitude of the location

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
partners
Array

Defines the partners (their logos will appear on the backend) assigned on this organisation by the service owner. applicable only for organisations of BUSINESS type

Object
id
string

The partner identifier

Example:
43f394c0-ece1-43a5-ab7d-b54ce9065fe7
billing_business_id
string

The billing business identifier

default_service_id
string

The default service identifier

Responses

200 200

OK

Body
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "name": "Delicious Food Group",
    "description": "Lorem Ipsum",
    "contact_info": [
        {
            "id": "CK1234567890123456789012345678",
            "type": "PHONE",
            "value": "info@crm.com",
            "name": "Head Office"
        }
    ],
    "industry_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "industry_sectors": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "business_activities": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "groups": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "inherit_from_parent": "false",
    "organisation_profile": {
        "registration_number": "1234",
        "tax_reference_number": "TAX1234",
        "vat_reference_number": "VAT1234",
        "registration_country": "CYP"
    },
    "cloud_name": "crmdotcom",
    "organisation_tags": [
        "Accounting"
    ],
    "service_organisations": [
        "1daf80b1-134b-36eb-7146-76dec04e6c5d"
    ],
    "contact_registry": "true",
    "locations": {
        "id": "a6cc4f88-cab1-4ab2-98d3-4655789277e2",
        "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",
        "care_of": "",
        "lat": 35.157115,
        "lon": 33.313719,
        "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "partners": [
        {
            "id": "43f394c0-ece1-43a5-ab7d-b54ce9065fe7"
        }
    ]
}
Delete Organisation
DELETE /organisations/{id}

Removes an organisation

Path variables

id
string GUID required

The organisation (identifier) that will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Organisations in Network
GET /organisations/{id}/network

Retrieve all organisations

Path variables

id
string GUID required

Parent organisation (identifier) whose child organisations will be retrieved

Example:
d332dd8a-254e-47c9-ba1f-3f369877a9b3

Request parameters

name
string optional

Filter based on the organisation’s name

Example:
Fantastic Dining
relationship
string optional

Filter based on the organisation’s relationship

Enumeration:
TRANSACTION_PROCESSOR
SERVICE_OWNER
BUSINESS
MERCHANT

(including service provider)

VENUE

(including service point)

groups
array of string GUID optional

Filter based on the organisation’s group (only Venues can be grouped)

Collection format: csv
Unique items: YES
industries
array of string GUID optional

Filter based on the organisation’s industry

Collection format: csv
industry_sectors
array of string GUID optional

Filter based on the organisation’s industry sector

Collection format: csv
organisation_tags
array of string GUID optional

Tag filter for organisation

Collection format: csv
business_activities
array of string GUID optional

Filter based on the organisation’s business activity

Collection format: csv
areas
array of string optional

Filter based on the organisation’s area

Collection format: csv
countries
array of string optional

Filter based on the organisation’s country

Collection format: csv
town_city
string optional

Filter based on the organisation’s town/city

child_count
array of string optional

Defines whether and which child organisations total number should be returned

Collection format: csv
Unique items: YES
creatives
array of string optional

List of Enums for Image Type

Collection format: csv
org_group
boolean optional

Defines whether the organisation group should be returned as part of the response

Example:
true
search_value
string optional

Defines the free text search parameter based on the provided type (e.g. name)

search_type
string optional

Defines the entitiy type that the search will be applied

Enumeration:
ORGANISATION
BUSINESS
MERCHANT
VENUE
BUSINESS_ACTIVITY
INDUSTRY
INDUSTRY_SECTOR
COUNTRY
AREA
ORGANISATION_GROUP
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
users_count
boolean optional

Defines whether the total number that belong to such organisation should be retrieved (applicable for departments)

Example:
false
operation_details
boolean optional

Defines whether the operation details of such organisations should be retrieved or not

Example:
true
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
status
string optional

Filter based on organisation status

Enumeration:
ACTIVE
INACTIVE
SUSPEND
tap_code
string optional

Filter based on TAP code

Example:
01-23-45-67-89-AB

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array

Information about the business network of a business semantic parent organisation

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisatio name

Example:
CRM.COM Cyprus
description
string

The organisation description

Example:
Lorem Ipsum
child_organisations
Array

Information about the child organisations

Unique items: YES
Object
relationship
string

Defines the relationship of the child organisation with the business semantic parent organisation

Enumeration:
TRANSACTION_PROCESSOR
SERVICE_OWNER
BUSINESS
MERCHANT
VENUE
count
integer

The total number of child organisations

Example:
21
groups
Array

Information about the organisation’s groups

Unique items: YES
Object
id
string GUID

The organisation group identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation group name

Example:
Seasonal
string
locations
Array

Information about the organisation’s location

Unique items: YES
Object

Information about the organisation’s location

id
string GUID

The location identifier

Example:
LOC123456234567345674567895678IK
name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
care_of
string

The care of information of the location

Example:
c/o Company
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
industry
Object

Information about the organisation’s industry

id
string GUID

The industry identifier

Example:
59106518-092e-8a08-7769-29f40dced0d1
name
string

The industry name

Example:
Restaurant
industry_sectors
Array

Information about the organisaion’s industry sectors

Unique items: YES
Object

Information about the industry sectors

id
string GUID

The industry sector identifier

Example:
9a857635-5ef3-aa4c-bd2c-90434070cb5a
name
string

The industry sector name

Example:
Bar
business_activities
Array

Information about the organisaion’s business activities

Unique items: YES
Object

Information about the business activity

id
string GUID

The business activity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The business activity name

Example:
Bar & Grill
users_count
integer

The total number of users for that organisation (applicable for departments)

Example:
24
operation_details
Object

The organisation operation details (retrieved only if operation_details = true)

opening_hours
Array

Details about the organisation’s working hours

Object
day_of_week
string

The day of the week that the organisation is open

Example:
MONDAY
opens
string

The time that the organisation opens

Example:
09:00
closes
string

The time that the organisation closes

Example:
20:00
operation
string

The opening hours for each organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
ANY
short_term_operations
Array

Details about the organisation’s availability to offer its services

Object
operation
string

The organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
is_closed
boolean

Defines whether the organisation is temporary closed for offering its services

Example:
false
contact_registry
boolean

Defines whether organisation supports contact registry

Example:
true
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
status
string

The status of the organisation

Enumeration:
ACTIVE
INACTIVE
SUSPEND
created_date
integer epoch

The date that such entity was created

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
GET /organisations/{id}/network HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "CRM.COM Cyprus",
            "description": "Lorem Ipsum",
            "child_organisations": [
                {
                    "relationship": "MERCHANTS",
                    "count": 21
                }
            ],
            "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",
                    "care_of": "",
                    "lat": "35.157115",
                    "lon": "33.313719",
                    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ],
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "type": "PROFILEIMAGE",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/offer.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
                        }
                    ]
                }
            ],
            "industry": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Restaurant"
            },
            "industry_sectors": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar"
                }
            ],
            "business_activities": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar & Grill"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
GET https://sandbox.crm.com/backoffice/v1/organisations/d332dd8a-254e-47c9-ba1f-3f369877a9b3/network?relationship=VENUE HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "CRM.COM Cyprus",
            "description": "Lorem Ipsum",
            "groups": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Seasonal"
                }
            ],
            "locations": [
                {
                    "id": "LOC123456234567345674567895678IK",
                    "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",
                    "care_of": "",
                    "lat": 35.157115,
                    "lon": 33.313719,
                    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ],
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "ATTACHMENT",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ],
            "industry": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Restaurant"
            },
            "industry_sectors": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar"
                }
            ],
            "business_activities": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar & Grill"
                }
            ],
            "users_count": 24,
            "operation_details": {
                "opening_hours": [
                    {
                        "day_of_week": "MONDAY",
                        "opens": "09:00",
                        "closes": "20:00",
                        "operation": "PICK_UP"
                    }
                ],
                "short_term_operations": [
                    {
                        "operation": "DELIVERY",
                        "is_closed": "false"
                    }
                ]
            },
            "contact_registry": "true"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Organisation
GET /organisations/{id}

Get details of a single Organisation

Path variables

id
string GUID required

The organisation (identifier) that will be retrieved

Example:
224ed6db-db6d-6878-58db-4381e5ef5669

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The organisation identifier

Example:
224ed6db-db6d-6878-58db-4381e5ef5669
name
string

The organisation name

Example:
Delicious Bite
description
string

The organisation description

Example:
Lorem Ipsum
org_type
string

The organisation type

Enumeration:
OPERATOR
SERVICE_OWNER
ORGANISATION
test_mode
boolean

Determines whether the organisation record will be used for test purposes

Example:
false
is_sandbox_on
boolean

Determines whether the sandbox mode is enabled or not

Example:
false
is_business
boolean

Defines whether the organisation is the primary business of the business network

Example:
false
groups
Array

Information about the organisation’s groups

Unique items: YES
Object
id
string GUID

The organisation group identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation group name

Example:
Seasonal
contact_info
Array

Information about the organisation’s contact details

Unique items: YES
Object

Information about the owner (admin user) of the organisation

id
string GUId

The contact detail identifier

Example:
CON123456234567345674567895678IK
name
string

The name of the contact information

Example:
Main Office
type
string

The type of the contact information

Enumeration:
EMAIL
PHONE
value
string

The value of the specific contact information

Example:
johndoe@deliciousfood.com
country_code
string

The country code related to the contact detail of type phone

Example:
CYP
locations
Array

Information about the organisation’s locations

Unique items: YES
Object

Information about the organisation’s location

id
string GUID

The location identifier

Example:
LOC123456234567345674567895678IK
name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
care_of
string

The care of information of the location

Example:
c/o Company
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
taps
Array

Information about the organisation’s transaction acquiring points (taps)

Unique items: YES
Object

Information about the organisation’s external references

id
string GUID

The transaction acquiring point identifier

Example:
TAP123456234567345674567895678IK
name
string

The transaction acquiring point name

Example:
ePOS
code
string

The transaction acquiring point code

Example:
EP12
is_active
boolean

Defines whether the transaction acquiring point is active or not

Example:
true
description
string

The transaction acquiring point description

Example:
electronic POS
external_ip
string

IP address of External Device

Example:
82.102.93.164
external_port
string

Port of the External IP

Example:
9100
tap_type
string

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
Object

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
industry
Object

Information about the organisation’s industry

id
string GUID

The industry identifier

Example:
59106518-092e-8a08-7769-29f40dced0d1
name
string

The industry name

Example:
Restaurant
industry_sectors
Array

Information about the organisation’s industry sectors

Unique items: YES
Object

Information about the industry sectors

id
string GUID

The industry sector identifier

Example:
9a857635-5ef3-aa4c-bd2c-90434070cb5a
name
string

The industry sector name

Example:
Bar
business_activities
Array

Information about the organisation’s business activities

Unique items: YES
Object

Information about the business activity

id
string GUID

The business activity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The business activity name

Example:
Bar & Grill
inherit_from_parent
boolean

Defines whether the new organisation will have the same industry, industry sectors and business activities as its parent organisation

Example:
false
organisation_profile
Object

Details about the organisation profile

registration_number
string

The organisation’s registration number

Example:
1234
tax_reference_number
string

The organisation’s TAX reference number

Example:
TAX1234
vat_reference_number
string

The organisation’s VAT reference number

Example:
VAT1234
registration_country
string

The company’s registrationc country code

Example:
CYP
organisation_id
string GUID

The parent organisation identifier that this organisation belongs to

Example:
7e8e39de-2f80-d2fe-b1f9-25b0cf4b2fbf
cloud_name
string

The name that the organisation will have on the cloud (applicable for Service Owner organisations; special characters not allowed)

Example:
crmdotcom
organisation_tags
Array

The tags of the organisation

string
Example:
Accounting
service_organisations
Array

The organisations (service owners) that the organisation (transaction processor) serves

Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
contact_registry
boolean

Defines whether the organisation supports contact registry

Example:
true
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
status
string

The status of the organisation

Enumeration:
ACTIVE
INACTIVE
SUSPEND
partners
Array

Defines the partners that are assigned to this organisation and their logos will be shown on the back-end SPA. Applicable only for organisations of type Business, where Service Owners will be responsible for assigning such information

Object
id
string GUID

The partner identifier

Example:
f4942b1d-efe2-258e-ebc2-6be805ce8b7c
name
string

The partner name

Example:
Best Partner
created_date
integer epoch

The date that such entity was created

billing_business
Object

Details regardifn the billing business

id
string

The billing business identifier

Example:
ed27b191-34a2-4782-654c-761b84a7c312
name
string

The billing business name

default_service
Object

The default service assigned to the organisation

id
string

The service identifier

name
string

The service name

sku
string

The service SKU

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "name": "Delicious Bite",
    "description": "Lorem Ipsum",
    "org_type": "SERVICE_OWNER",
    "test_mode": "false",
    "is_sandbox_on": "false",
    "is_business": "false",
    "groups": [
        {
            "id": "OGD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Seasonal"
        }
    ],
    "contact_info": [
        {
            "id": "CON123456234567345674567895678IK",
            "name": "Main Office",
            "type": "PHONE",
            "value": "johndoe@deliciousfood.com",
            "country_code": "CYP"
        }
    ],
    "locations": [
        {
            "id": "LOC123456234567345674567895678IK",
            "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",
            "care_of": "c/o Company",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    ],
    "taps": [
        {
            "id": "TAP123456234567345674567895678IK",
            "name": "ePOS",
            "code": "EP12",
            "is_active": "true",
            "description": "electronic POS",
            "external_ip": "82.102.93.164",
            "external_port": "9100",
            "tap_type": "EXTERNAL_REF",
            "external_type": {
                "id": "4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0",
                "code": "TAP001"
            }
        }
    ],
    "industry": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DRT",
        "name": "Restaurant"
    },
    "industry_sectors": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DWQ",
            "name": "Bar"
        }
    ],
    "business_activities": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DBU",
            "name": "Bar & Grill"
        }
    ],
    "inherit_from_parent": "false",
    "organisation_profile": {
        "registration_number": "1234",
        "tax_reference_number": "TAX1234",
        "vat_reference_number": "VAT1234",
        "registration_country": "CYP"
    },
    "organisation_id": "7e8e39de-2f80-d2fe-b1f9-25b0cf4b2fbf",
    "cloud_name": "crmdotcom",
    "organisation_tags": [
        "Accounting"
    ],
    "service_organisations": [
        {
            "id": "ed165bb7-666e-d55c-7e3d-1127909d10a3",
            "name": "CRMdotCOM"
        }
    ],
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "ATTACHMENT",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ],
    "contact_registry": "true",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "status": "SUSPEND",
    "partners": [
        {
            "id": "43f394c0-ece1-43a5-ab7d-b54ce9065fe7",
            "name": "Yellow Umbrella Corp."
        }
    ]
}
Get Organisation Activity Feed
GET /organisations/{id}/activity_feed

Get the activity feed of a single organisation

Path variables

id
string GUID required

The organisation (identifier) whose activity will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

activity_type
string optional

The activity type

Enumeration:
INVOICE
PAYMENT
CREDIT_NOTE
REFUND
TOP_UP
created_date
integer epoch optional

The created date of the activity (no time)

Example:
1576486645
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array

Details about the activity feed

Object
id
string GUID

The activity (feed) identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The entity’s number

Example:
I10003
reference_number
string

The entity’s reference number

Example:
Ref12345678
code
string

The entity’s code

Example:
123456789ABE2364
state
string

The entity’s life cycle state

Example:
POSTED
created_date
integer epoch

The entity’s created date

Example:
1576486645
activity_type
string

The activity (feed) type

Example:
INVOICE
direction
string

The activity (feed) direction

Example:
OUTGOING
notes
string

The activity (feed) notes

Example:
This Invoice is created for November 2019
type
string

The entity’s type name

Example:
INVOICE
total_amount
integer

The entity’s total amount

Example:
200
currency
string

The entity’s currency

Example:
EUR
due_date
integer epoch

The entity’s due date in case of Invoices

Example:
1576486645
topup_entity
Object

The entity that the topup was performed for

id
string GUID

The top up identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The number or code of the topup entity

Example:
AC00123 John Johnson
type
string

The type of the topup entity

Example:
ACCOUNT
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/activity_feed HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "activity_feed": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "number": "I10003",
            "reference_number": "Ref12345678",
            "code": "123456789ABE2364",
            "state": "POSTED",
            "created_date": 1576486645,
            "activity_type": "INVOICE",
            "direction": "OUTGOING",
            "notes": "This Invoice is created for November 2019",
            "type": "INVOICE",
            "total_amount": 200,
            "currency": "EUR",
            "due_date": 1576486645,
            "topup_entity": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "number": "AC00123 John Johnson",
                "type": "ACCOUNT"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Switch Organisations
POST /organisations/{id}/switch

Switch the user to another organisation

Path variables

id
string GUID required

The organisation (identifier) that will be switched to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

As part of “changing organisations that an user belongs to” flow, the user will have a different role as assigned to him when he was invited to the organisation that was switched to

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/switch HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Masquerade Organisations
POST /organisations/{id}/masquerade

Switch the user to another organisation

Path variables

id
string GUID required

The organisation (identifier) that will be masqueraded to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

MASQUERADED USER PEMISSIONS

As part of “masquerade” flow, the masqueraded user will have the same role as the one from the initial organisation that such user signed in.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/masquerade HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Actions on Organisations
POST /organisations/{id}/actions

Perform an action on a single organisation

Path variables

id
string GUID required

The organisation (identifier) that an action will be applied on it

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
action
string required

The action that will be applied on the organisation

Enumeration:
MODE

Enable live mode on the organisation

ACTIVE
INACTIVE
SUSPEND
COPY
name
string nullable

The organisation name that will be used when copying an organisation (applicable when action == COPY)

Example:
CRM

Responses

200 200

OK

Body
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "MODE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Organisation Media Groups
POST /organisations/{id}/media_groups

Link an organisation with one or many media groups

Path variables

id
string GUID required

The organisation (identifier) that media groups will be updated

Example:
sdfsfsdf-32-fwef-wef-wefwef23

Notes

MEDIA UPLOAD

Uploading media for an organisation requires the execution of the following APIs

  1. Create new Media Group
  2. Create Organisation Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/sdfsfsdf-32-fwef-wef-wefwef23/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK 
Import Organisations (Internal)
POST /organisations/import

Retrieve all organisations to be added as merchants or venues to an existing business

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
integration
string required

Integration Adapter to provide import

Enumeration:
JCC_MERCHANT
external_id
string required nullable

External ID for the integration to retrieve the venues / outlets, in the case of JCC a merchant ID

Responses

200 200

The request has succeeded

Body
Object
content
Array

Information about the business network of a business semantic parent organisation

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisatio name

Example:
CRM.COM Cyprus
description
string

The organisation description

Example:
Lorem Ipsum
child_organisations
Array

Information about the child organisations

Unique items: YES
Object
relationship
string

Defines the relationship of the child organisation with the business semantic parent organisation

Enumeration:
TRANSACTION_PROCESSOR
SERVICE_OWNER
BUSINESS
MERCHANT
VENUE
count
integer

The total number of child organisations

Example:
21
groups
Array

Information about the organisation’s groups

Unique items: YES
Object
id
string GUID

The organisation group identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation group name

Example:
Seasonal
string
locations
Array

Information about the organisation’s location

Unique items: YES
Object

Information about the organisation’s location

id
string GUID

The location identifier

Example:
LOC123456234567345674567895678IK
name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
care_of
string

The care of information of the location

Example:
c/o Company
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
industry
Object

Information about the organisation’s industry

id
string GUID

The industry identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The industry name

Example:
Restaurant
industry_sectors
Array

Information about the organisaion’s industry sectors

Unique items: YES
Object
id
string GUID

The industry sector identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The industry sector name

Example:
Bar
business_activities
Array

Information about the organisaion’s business activities

Unique items: YES
Object
id
string GUID

The business activity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The business activity name

Example:
Bar & Grill
users_count
integer

The total number of users for that organisation (applicable for departments)

Example:
24
operation_details
Object

The organisation operation details (retrieved only if operation_details = true)

opening_hours
Array

Details about the organisation’s working hours

Object
day_of_week
string

The day of the week that the organisation is open

Example:
MONDAY
opens
string

The time that the organisation opens

Example:
09:00
closes
string

The time that the organisation closes

Example:
20:00
operation
string

The opening hours for each organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
ANY
short_term_operations
Array

Details about the organisation’s availability to offer its services

Object
operation
string

The organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
is_closed
boolean

Defines whether the organisation is temporary closed for offering its services

Example:
false
contact_registry
boolean

Defines whether organisation supports contact registry

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/import HTTP/1.1 

Content-Type: application/json

{
    "integration": "JCC_MERCHANT",
    "external_id": "0000257"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "CRM.COM Cyprus",
            "description": "Lorem Ipsum",
            "child_organisations": [
                {
                    "relationship": "TRANSACTION_PROCESSOR",
                    "count": 21
                }
            ],
            "groups": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Seasonal"
                },
                ""
            ],
            "locations": [
                {
                    "id": "LOC123456234567345674567895678IK",
                    "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",
                    "care_of": "",
                    "lat": 35.157115,
                    "lon": 33.313719,
                    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ],
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "ATTACHMENT",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ],
            "industry": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Restaurant"
            },
            "industry_sectors": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar"
                }
            ],
            "business_activities": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "Bar & Grill"
                }
            ],
            "users_count": 24,
            "operation_details": {
                "opening_hours": [
                    {
                        "day_of_week": "MONDAY",
                        "opens": "09:00",
                        "closes": "20:00",
                        "operation": "DELIVERY"
                    }
                ],
                "short_term_operations": [
                    {
                        "operation": "PICK_UP",
                        "is_closed": "false"
                    }
                ]
            },
            "contact_registry": "true"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Billing Relationship
GET /organisations/{id}/billing

Retrieves a relationship between an organisation as the billing business and a contact.

Path variables

id
string GUID required

The organisation (identifier) that billing relationship will be retrieved

Example:
db560dec-4097-655e-25b3-d0fe95698bd0

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
organisation
Object

Details about the organisation that does the billing

id
string GUID

The organisation identifier

Example:
db560dec-4097-655e-25b3-d0fe95698bd0
name
string

The organisation name

Example:
CRM billing
api_key
string

This returns the public API key for the billing organisation

Example:
5bd2fd1d-3f49-3f51-fddc-76bb419880c7
billing_contact
Object

Authentication details of the contact that will be billed due to its billing relaiton to the billing organisation

access_token
string

This returns the jwt token associated to the contact of the billing organisation

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
refresh_token
string

Refresh token used when access token get expired

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg
exp
integer

Expiration of access token

contact
Object

Billing Contact details

id
string

The contact’s unique identifier

title
string

Contact’s title

Example:
Mr
first_name
string

Contact first name

Example:
John
company_name
string
last_name
string
Example:
Doe
avatar
string
Example:
avatar
is_verified
boolean
organisations
Array
Object
external_id
string
Example:
QWERTY12345671234567324ETFTGBY78
org_type
string
Enumeration:
SERVICE_OWNER
ORGANISATION
name
string
Example:
CRMdotCOM
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/db560dec-4097-655e-25b3-d0fe95698bd0/billing HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "organisation": {
        "id": "db560dec-4097-655e-25b3-d0fe95698bd0",
        "name": "CRM billing",
        "api_key": "5bd2fd1d-3f49-3f51-fddc-76bb419880c7"
    },
    "billing_contact": {
        "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
        "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg",
        "exp": 1,
        "contact": {
            "id": "",
            "title": "Mr",
            "first_name": "John",
            "company_name": "",
            "last_name": "Doe",
            "avatar": "avatar",
            "is_verified": true
        },
        "organisations": [
            {
                "external_id": "QWERTY12345671234567324ETFTGBY78",
                "org_type": "SERVICE_OWNER",
                "name": "CRMdotCOM"
            }
        ]
    }
}
API Keys
POST /organisations/{id}/apikeys
PUT /organisations/{id}/apikeys/{apikey_id}
DELETE /organisations/{id}/apikeys/{apikey_id}
GET /organisations/{id}/apikeys
GET /organisations/{id}/apikeys/{apikey_id}
POST /organisations/{id}/apikeys/{apikey_id}
Create API Key
POST /organisations/{id}/apikeys

Create an active API Key for a specific organisation

Path variables

id
string GUID required

The organisation (identifier) where an API Key will be created

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The api key name

Example:
Registration Portal
type
string required

Defines the type of the api key

Enumeration:
PUBLIC
SECRET

Responses

200 200

OK

Body
Object
id
string GUID

The api key identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
key
string

The non-encrypted secret key that will be used for subsuquent API authentication

Example:
123465789
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Registration Portal",
    "environment": "TEST",
    "type": "SECRET"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD",
    "key": "123465789"
}
Update API Key
PUT /organisations/{id}/apikeys/{apikey_id}

Update a single api key of a specific organisation

Path variables

id
string GUID required

The organisation (identifier) whose api key will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
apikey_id
string GUID required

The api key (identifier) that will be updated

Example:
SEC1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The api key name

Example:
Registration Portal
is_active
boolean nullable

Defines whether the api key will be active or not

Example:
false

Responses

200 200

OK

Body
Object
id
string GUID

The api key identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys/SEC1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "name": "Registration Portal",
    "is_active": "false"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD"
}
Delete API Key
DELETE /organisations/{id}/apikeys/{apikey_id}

Delete a single api key of a specific organisation

Path variables

id
string GUID required

The organisation (identifier) whose api key will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
apikey_id
string GUID required

The api key (identifier) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List API Keys
GET /organisations/{id}/apikeys

Retrieve all API Keys for a specific organisation

Path variables

id
string GUID required

The organisation (identifier) whose api keys will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

name
string optional

Filter based on the name

Example:
Registration Key
type
string optional

Filter based on the api key type

Enumeration:
PUBLIC
SECRET
is_active
boolean optional

Filters based on whether API Keys are active or not

Example:
true
is_default
boolean optional

Filters the default API Key

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation’ api keys

Object
id
string GUID

The api key identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The api key name

Example:
Registration Name
type
string

Defines the type of the api key

Enumeration:
PUBLIC
SECRET
is_active
boolean

Defines whether the api (public or secret) key is active or not

Example:
true
public_key
string

The public api key’s value

Example:
API1E31269B76D
obfuscated
string

The secret api key obfuscated value

Example:
********MG12
encrypted
string

The secret api key encrypted value

Example:
qwertyasd123
active_end
integer epoch

Defines the date up until the secret api key will be active

Example:
1580292120
is_default
boolean

Defines if the api key is the default one (applicable only for public API keys)

Example:
false
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Registration Name",
            "type": "PUBLIC",
            "is_active": "true",
            "public_key": "API1E31269B76D",
            "obfuscated": "********MG12",
            "encrypted": "qwertyasd123",
            "active_end": 1580292120,
            "is_default": "false"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get API Key
GET /organisations/{id}/apikeys/{apikey_id}

Get details of a single API Key

Path variables

id
string GUID required

The organisation (identifier) whose api keys will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
apikey_id
string GUID required

The api key (identifier) that will be retrieved

Example:
API1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation’ api keys

Object
id
string GUID

The organisation’s api key identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The api key name

Example:
Registration Key
type
string

Defines the type of the api key

Enumeration:
PUBLIC
SECRET
is_active
boolean

Defines whether the api (public or secret) key is active or not

Example:
true
public_key
string

The public api key’s value

Example:
API1E31269B76D
obfuscated
string

The secret api key obfuscated value

Example:
********ML71
encrypted
string

The secret api key encrypted value

Example:
qwerty1234a8
active_end
integer epoch

Defines the date up until the secret api key will be active

Example:
1580292120
is_default
boolean

Defines if the api key is the dwfault one (applicable only for public API keys)

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2

Retrieve details for a Public API Key

GET /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys/API1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Registration Key",
            "type": "PUBLIC",
            "is_active": "true",
            "public_key": "API1E31269B76D"
        }
    ]
}

Retrieve details for a Secret API Key

GET /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys/API1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Payment Gateway",
            "type": "SECRET",
            "is_active": "true",
            "obfuscated": "********ML71",
            "encrypted": "qwerty1234a8",
            "active_end": 1580292120
        }
    ]
}
Roll API Key
POST /organisations/{id}/apikeys/{apikey_id}

Roll a single api key of a specific organisation

Path variables

id
string GUID required

The organisation (identifier) whose api key will be rolled

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
apikey_id
string GUID required

The api key (identifier) that will be rolled

Example:
API1E31269B76D7A65ACCE45B2E68DFD

Notes

Only secret keys can be rolled. The previous key will be revoked (and no longer can be used until expired), while a new one will be generated based on GUID standard methods.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
expiry_date
integer epoch nullable

Defines up until when the api key will be valid (applicable only for secret api key)

Example:
1582034284

Responses

200 200

OK

Body
Object
id
string GUID

The organisation’s api key identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
key
string

The non-encrypted api key value that will be used for subsuquent API authentication

Example:
123456789
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/apikeys/API1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD"
}
Business Activities
GET /organisations/businessactivities
List Business Activities
GET /organisations/businessactivities

Search for organisation’s business activities

Request parameters

name
string optional

The business activity name

Example:
Bar & Grill

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The business activity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The business activity name

Example:
Information Services
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/businessactivities HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": ""
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Financial Operations
POST /organisations/{id}/accounts
GET /organisations/{id}/accounts
Create Organisation Account
POST /organisations/{id}/accounts

Create an account for a specific organisation. An Account can only be created for a Business or a Merchant or a Service Provider.

Path variables

id
string GUID required

The organisation (identifier) that an account will be created

Example:
c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of account

Example:
USD Second Accont
currency_code
string

The currency for the account

Example:
EUR
is_primary
boolean

Defines whether the account is the primary one

Example:
true
billing_address_id
string GUID

The billing address identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
classification_id
string GUID

The account classification identifier

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 OK
Body
Object
id
string GUID

The organisation account identifier

Example:
c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4/accounts HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "USD Second Accont",
    "currency_code": "EUR",
    "is_primary": true,
    "billing_address_id": "4AD9C84FA60F9FE407140E20F707726A",
    "classification_id": "4AD9C84FA60F9FE407140E20F707726A"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4"
}
List Organisation Accounts
GET /organisations/{id}/accounts

List all accounts of an organisation

Path variables

id
string GUID required

The organisation (identifier) whose accounts wil be retrieved

Example:
c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
is_primary
boolean optional

Retrive only the primary account of an Organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
is_primary
boolean

Defines whether the account is the primary one

Example:
true
name
string

The account name

Example:
Default
number
string

The account number

Example:
AC123456
life_cycle _state
string

The life cycle state of the account

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
currency_code
string

The account currency code

Example:
EUR
balance
number

The account balance

Example:
12.33
credit_limit
number

The account credit limit

Example:
1.22
overdue_amount
number

The account overdue amount

Example:
1.11
classification
Object

Account Classification Details

id
string GUID

The classification identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The classification name

Example:
VIP
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/c6e6bcc8-ef76-45a9-a7c1-b45efaa6fdb4/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",
            "balance": 12.33,
            "credit_limit": 1.22,
            "overdue_amount": 1.11,
            "classification": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "VIP"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Operation Details
PUT /organisations/{id}/operation_details
GET /organisations/{id}/operation_details
Set Operation Details
PUT /organisations/{id}/operation_details

Update an organisation’s operational details (e.g. opening hours)

Path variables

id
string GUID required

The organisation (identifier) whose operation details will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
opening_hours
Array nullable

Details about the organisation’s working hours

Object
day_of_week
string required

The day of the week that the organisation is open

Example:
SUNDAY
opens
string required

The time that the organisation opens

Example:
09:00
closes
string required

The time that the organisation closes

Example:
20:00
operation
string required

The opening hours for each organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
ANY
short_term_operations
Array nullable

Details about the organisation’s availability to offer its services

Object
operation
string required

The organisation’s operation

Enumeration:
DELIVERY
PICK_UP
ANY
is_closed
boolean nullable

Defines whether the organisation is temporary closed for offering its services

Example:
false

Responses

200 200

OK

Body
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/operation_details HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "opening_hours": [
        {
            "day_of_week": "MONDAY",
            "opens": "09:00",
            "closes": "20:00",
            "operation": "ANY"
        }
    ],
    "short_term_operations": [
        {
            "operation": "ANY",
            "is_closed": "false"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Get Operation Details
GET /organisations/{id}/operation_details

Retrieve an organisation’s operational details (e.g. opening hours)

Path variables

id
string GUID required

The organisation (identifier) whose operation details will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
opening_hours
Array

Details about the organisation’s working hours

Object
day_of_week
string

The day of the week that the organisation is open

Example:
MONDAY
opens
string

The time that the organisation opens

Example:
09:00
closes
string

The time that the organisation closes

Example:
20:00
operation
string

The opening hours for each organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
ANY
short_term_operations
Array

Details about the organisation’s availability to offer its services

Object
operation
string

The organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
is_closed
boolean

Defines whether the organisation is temporary closed for offering its services

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/operation_details HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "opening_hours": [
        {
            "day_of_week": "MONDAY",
            "opens": "09:00",
            "closes": "20:00",
            "operation": "PICK_UP"
        }
    ],
    "short_term_operations": [
        {
            "operation": "DELIVERY",
            "is_closed": "false"
        }
    ]
}
Organisation Groups
POST /organisationgroups
PUT /organisationgroups/{orggroup_id}
DELETE /organisationgroups/{orggroup_id}
GET /organisationgroups
GET /organisationgroups/{orggroup_id}
Create Organisation Group
POST /organisationgroups

Create an organisation group

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The organisation group name

Example:
Seasonal
description
string nullable

The organisation group description

Example:
Lorem Ipsum

Responses

200 200

OK

Body
Object
id
string GUID

The organisation group identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisationgroups HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Seasonal",
    "description": "Lorem Ipsum"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Organisation Group
PUT /organisationgroups/{orggroup_id}

Update an existing organisation group

Path variables

orggroup_id
string GUID required

The organisation group (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The organisation group name

Example:
Seasonal
description
string nullable

The organisation group description

Example:
Lorem Ipsum

Responses

200 200

OK

Body
Object
id
string GUID

The organisation group identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /organisationgroups/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Seasonal",
    "description": "Lorem Ipsum"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Organisation Group
DELETE /organisationgroups/{orggroup_id}

Delete an existing organisation group

Path variables

orggroup_id
string GUID required

The organisation group (identifier) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /organisationgroups/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Organisation Groups
GET /organisationgroups

Retrieve all organisation groups

Request parameters

name
string optional

Filter based on the organisation group name

Example:
Nicosia Dinners

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information about the organisation groups

Object
id
string GUID

The organisation group identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation group name

Example:
Nicosia Dinners
description
string

The organisation group description

Example:
Lorem Ipsum
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisationgroups HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Nicosia Dinners",
            "description": "Lorem Ipsum"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Organisation Group
GET /organisationgroups/{orggroup_id}

Get details of a single organisation group

Path variables

orggroup_id
string GUID required

The organisation group (identifier) whose secret key will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The organisation group identifier

Example:
API1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation group name

Example:
Seasonal
description
string

The organisation group description

Example:
Lorem Ipsum
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /organisationgroups/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "API1E31269B76D7A65ACCE45B2E68DFD",
    "name": "Seasonal",
    "description": "true"
}
Organisation Licenses
GET /organisations/{id}/licenses
List Organisation Licenses
GET /organisations/{id}/licenses

Returns list of all licenses used by the organisation

Path variables

id
string GUID required

The orginaisation (identifier) for which the licenses will be retreived

Example:
124c227e-85b7-84d6-f19a-f1dc69101b69

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
licenses
Array

The list of licenses of an organisation

Object
id
string GUID

The license identifier

Example:
bae010f4-7e70-d66e-32fb-31d716e1b824
name
string

The name of the license

Example:
Basic Rewards
description
string

The description of the license

Example:
The basic Rewards Package
Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/124c227e-85b7-84d6-f19a-f1dc69101b69/licenses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "licenses": [
        {
            "id": "bae010f4-7e70-d66e-32fb-31d716e1b824",
            "name": "Basic Rewards",
            "description": "The basic Rewards Package"
        }
    ]
}
Organisation Locations
POST /organisations/{id}/locations
PUT /organisations/{id}/locations/{location_id}
DELETE /organisations/{id}/locations/{location_id}
Add Organisation Location
POST /organisations/{id}/locations

Add a new location for an existing Organisation

Path variables

id
string GUID required

The organisation (identifier) whose locations will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the location

Example:
Head Office
address_line_1
string required

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string nullable

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string nullable

The state/province/county of the location

Example:
Egkomi
town_city
string required

The town/city of the location

Example:
Nicosia
postal_code
string required

The postal code of the location

Example:
2415
country_code
string required

The country of the location

Example:
CY
care_of
string nullable

The care of information of the location

lat
number nullable

The latitude of the location

Example:
33.313719
lon
number nullable

The longitude of the location

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0

Responses

200 200

OK

Body
Object
id
string GUID

The organisation’s location identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/locations HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "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",
    "care_of": "",
    "lat": "35.157115",
    "lon": "33.313719",
    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Organisation Location
PUT /organisations/{id}/locations/{location_id}

Update a location for an existing Organisation

Path variables

id
string GUID required

The organisation (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
location_id
string GUID required

The organisation’s location (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the location

Example:
Head Office
address_line_1
string nullable

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string nullable

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string nullable

The state/province/county of the location

Example:
Egkomi
town_city
string nullable

The town/city of the location

Example:
Nicosia
postal_code
string nullable

The postal code of the location

Example:
2415
country_code
string nullable

The country of the location

Example:
CY
care_of
string nullable

The care of information of the location

lat
number nullable

The latitude of the location

Example:
35.157115
lon
number nullable

The longitude of the location

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0

Responses

200 200

OK

Body
Object
id
string GUID

The organisation’s location identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/locationsCAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "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",
    "care_of": "",
    "lat": "35.157115",
    "lon": "33.313719",
    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Organisation Location
DELETE /organisations/{id}/locations/{location_id}

Delete a location for an existing Organisation

Path variables

id
string GUID required

The organisation (identifier) whose location will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
location_id
string GUID required

The organisation’s (identifier) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/locationsCAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Organisation Payment Methods
POST /organisations/{id}/payment_methods
PUT /organisations/{id}/payment_methods/{payment_method_id}
DELETE /organisations/{id}/payment_methods/{payment_method_id}
GET /organisations/{id}/payment_methods
Add Payment Methods
POST /organisations/{id}/payment_methods

Add a new payment method for an organisation

Path variables

id
string GUID required

The organisation (identifier) that a payment method will be created

Example:
4db61210-49b0-0267-6de6-82ca63a35903

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the payment method

Example:
Primary payment method
type
string required

The payment method’s type

Enumeration:
CARD
ACCOUNT_DEBIT
SETTLEMENT_ACCOUNT
WALLET
Example:
SETTLEMENT_ACCOUNT
is_primary
boolean nullable

Marks the payment method as the organisation’s primary one

Example:
true
is_backup
boolean nullable

Marks the payment method as the backup

Example:
false
notes
string nullable

Notes related to te payment method

Example:
some notes
settlement_account
Object required nullable

The account’s main information. Required and applicable if the payment method type is ACCOUNT

name
string nullable

The account name

Example:
Primary Account
payment_gateway
Object required

Information regarding the account’s payment gateway

gateway
string

The payment gateway related to the payment method

Enumeration:
JCC_MERCHANT
gateway_identifier
string required

The identifier used on payment gateway

Example:
0000257
account_debit
Object nullable

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string nullable

The bank account number.

Example:
001002001
iban
string required nullable

The IBAN code.

Example:
0143240434320434
bank
string nullable

The name of the customer’s bank

Example:
Barclays
bank_code
string nullable

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string nullable

The bank account swift number

Example:
12345678
sort_code
string nullable

The sort code

Example:
20-02-53
mandate
Object
reference
string
type
string

The mandate (sequence) type

Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
sign_date
integer epoch
Example:
1654756878
termination_date
integer epoch
Example:
1654756887
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
integration_id
string

The payment gateway’s integration identifier

account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_state
string
address_city
string
address_zip
string
address_coutry
string
use_billing_address
boolean
country
string

The country the bank account is located in.

Example:
CY
currency
string
Example:
EUR
card
Object nullable

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
Default Card
brand
string

The card’s brand

Example:
VISA
first6
string

The card’s first 6 digits

Example:
424242
last4
string

The card’s lat 4 digits

Example:
4242
expiration_month
integer

The card’s expiration month

Example:
1
expiration_year
integer

The card’s expiration year

Example:
2020
country_of_issue
string

The card’s coutry of issue (3 code based)

Example:
CYP
card_holder_details
Object

Details about the cardholder owner

card_holder_name
string

The name of the card holder

Example:
John Doe
address_line_1
string

The address related to the card

Example:
Elia Papakyriakou
address_line_2
string

Additional address information related to the card

Example:
7 Tower Star
address_city
string

The city related to the card

Example:
Nicosia
address_zip
string

The zip code related to the card

Example:
2415
address_state
string

The state related to the card

Example:
Nicosia
address_country
string

The country related to the card

Example:
CYP
gateway_token
Array

Details about the gateway that a card related token was issued

Object
gateway
string nullable

Defines the gateway that issued such token

Enumeration:
JCC
SETTLE
integration_id
string GUID nullable

The gateway integration (identifier)

Example:
bce504a4-f712-5262-183c-f58218a7a0ed
token
string required

The card related token

Example:
Xt5EWLLDS7FJjR1c

Responses

200 200

OK

Body
Object
id
string GUID

The payment method identifier

Example:
5a56dec4-144c-0d73-f749-9030879280ca
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/4db61210-49b0-0267-6de6-82ca63a35903/payment_methods HTTP/1.1 

Content-Type: application/json

{
    "name": "Primary payment method",
    "type": "SETTLEMENT_ACCOUNT",
    "is_primary": "true",
    "is_backup": "false",
    "notes": "some notes", 
    "settlement_account": {
        "name": "Primary Account",
        "payment_gateway": {
            "gateway": "JCC_MERCHANT",
            "gateway_identifier": "0000257"
        }
    },
    "account_debit": {
        "account_name": "",
        "account_number": "001002001",
        "iban": "0143240434320434",
        "bank": "Barclays",
        "bank_code": "0032933-1123",
        "branch": "Ascot",
        "swift": "12345678",
        "sort_code": "20-02-53",
        "mandate": {
            "reference": "",
            "sign_date": 1
        },
        "account_type": "SAVINGS",
        "integration_id": ""
    },
    "card": {
        "name": "Default Card",
        "brand": "VISA",
        "first6": "424242",
        "last4": "4242",
        "expiration_month": 1,
        "expiration_year": 2020,
        "country_of_issue": "CYP",
        "card_holder_details": {
            "card_holder_name": "John Doe",
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Star",
            "address_city": "Nicosia",
            "address_zip": "2415",
            "address_state": "Nicosia",
            "address_country": "CYP"
        },
        "gateway_token": [
            {
                "gateway": "SETTLE",
                "integration_id": "bce504a4-f712-5262-183c-f58218a7a0ed",
                "token": "Xt5EWLLDS7FJjR1c"
            }
        ]
    }
}
Update Payment Method
PUT /organisations/{id}/payment_methods/{payment_method_id}

Update an existing payment method for an organisation

Path variables

id
string GUID required

The organisation (identifier) whose paymeny method will be updated

Example:
2b2460d3-9753-148e-2f5b-f30c0562f5a5
payment_method_id
string GUID required

The payment method (identifier) that will be updated

Example:
5a56dec4-144c-0d73-f749-9030879280ca

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
is_primary
boolean nullable

Marks the payment method as the organisation’s primary one

Example:
true
is_backup
boolean nullable

Marks the payment method as the backup

Example:
false
notes
string nullable

The payment method notes

Example:
some notes
settlement_account
Object nullable

The account’s main information. Required and applicable if the payment method type is ACCOUNT

name
string nullable

The account name

Example:
Primary Account
payment_gateway
Object required

Information regarding the account’s payment gateway

gateway
string

The payment gateway related to the payment method

Enumeration:
JCC_MERCHANT
gateway_identifier
string required

The identifier used on payment gateway

Example:
0000257
account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string nullable

The bank account number.

Example:
001002001
iban
string required nullable

The IBAN code.

Example:
0143240434320434
bank
string nullable

The name of the customer’s bank

Example:
Barclays
bank_code
string nullable

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string nullable

The bank account swift number

Example:
12345678
sort_code
string nullable

The sort code

Example:
20-02-53
country
string

The country the bank account is located in.

Example:
CY
mandate
Object
reference
string
type
string

The mandate (sequence) type

Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
sign_date
integer
termination_date
integer
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
currency
string
Example:
EUR
account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_state
string
address_city
string
address_zip
string
address_coutry
string
use_billing_address
boolean

Responses

200 200

OK

Body
Object
id
string GUID

The payment method identifier

Example:
5a56dec4-144c-0d73-f749-9030879280ca
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/organisations/2b2460d3-9753-148e-2f5b-f30c0562f5a5/payment_methods/5a56dec4-144c-0d73-f749-9030879280ca HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "is_primary": "true",
    "is_backup": "false",
    "notes": "some notes",
    "settlement_account": {
        "name": "Primary Account",
        "payment_gateway": {
            "gateway": "JCC_MERCHANT",
            "gateway_identifier": "0000257"
        }
    },
    "account_debit": {
        "account_name": "",
        "account_number": "001002001",
        "iban": "0143240434320434",
        "bank": "Barclays",
        "bank_code": "0032933-1123",
        "branch": "Ascot",
        "swift": "12345678",
        "sort_code": "20-02-53",
        "mandate": {
            "reference": "",
            "sign_date": 1
        },
        "account_type": "SAVINGS",
        "integration_id": ""
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "5a56dec4-144c-0d73-f749-9030879280ca"
}
Remove Payment Method
DELETE /organisations/{id}/payment_methods/{payment_method_id}

Remove a payment method from an organisation

Path variables

id
string GUID required

The organisation (identifier) whose payment method will be removed

Example:
1c7eb6f5-b11e-ee69-0bdd-e4d2b3a93c0c
payment_method_id
string GUID required

The payment method (identifier) that will be removed

Example:
5a56dec4-144c-0d73-f749-9030879280ca

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://staging.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/payment_methods/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 200 OK 
List Payment Methods
GET /organisations/{id}/payment_methods

List payment methods related to an organisation account

Path variables

id
string GUID required

The organisation (identifier) whose payment methods will be retrieved

Example:
ff27b927-d346-4369-aba3-4478de764816

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
type
string optional

Filter based on payment method type

Enumeration:
CARD
ACCOUNT_DEBIT
SETTLEMENT_ACCOUNT
WALLET
Example:
SETTLEMENT_ACCOUNT
is_primary
boolean optional
is_backup
boolean optional

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array

The payment method identifier

Object
id
string GUID

The payment method identifier

Example:
ff27b927-d346-4369-aba3-4478de764816
name
string
payment_method_type
string

The payment method type

Enumeration:
CARD
ACCOUNT_DEBIT
SETTLEMEN_ACCOUNT
WALLET
is_primary
boolean

Indicates which payment mehod is the organisation’s primary one

Example:
true
is_backup
boolean

Indicates which payment mehod is the organistaion’s backup one

Example:
false
notes
string

Notes related to the payment method

Example:
Payment Method Notes
settlement_account
Array

The account details (applicable if the payment method is set to ACCOUNT)

Object
name
string

The account name

Example:
Primary Account
payment_gateway
Object

Information regarding the account’s payment gateway

gateway
string

The payment gateway related to the payment method

Enumeration:
JCC_MERCHANT
gateway_identifier
string

The identifier used on payment gateway

Example:
1245
account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string

The bank account number.

Example:
001002001
iban
string

The IBAN code.

Example:
0143240434320434
bank
string

The name of the customer’s bank

Example:
Barclays
bank_code
string

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string

The identifier of the bank branch

Example:
Ascot
swift
string

The bank account swift number

Example:
12345678
sort_code
string

The sort code

Example:
20-02-53
country
string

The country the bank account is located in.

Example:
CY
currency
string
Example:
EUR
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
mandate
Object
reference
string
sign_date
integer
termination_date
integer
type
string
Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_city
string
address_state
string
address_zip
string
address_country
string
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
card
Object

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
Default Card
brand
string

The card’s brand

Example:
VISA
funding_type
string

The type of the event

Enumeration:
CREDIT
DEBIT
PREPAID
Example:
CREDIT
first6
string

The first 6 digits of the card. Either the card number or the first 6 and last 4 digits must be specified

last4
string

The last 4 digits f the card. Either the card number or the first 6 and last 4 digits must be specified

expiration_month
integer

The card expiration month

Example:
1
expiration_year
integer

The card expiration year

Example:
2020
country_of_issue
string

The card issue country (3 char country code)

Example:
CYP
cvc
string
card_holder_details
Object

Information about the card holder

card_holder_name
string

The name of the card holder

Example:
John Doe
address_line_1
string

The address related to the card

Example:
Elia Papakyriakou
address_line_2
string

Additional address information related to the card

Example:
7 Tower Star
address_city
string

The city related to the card

Example:
Nicosia
address_zip
string

The zip code related to the card

Example:
2415
address_state
string

The state related to the card

Example:
Nicosia
address_country
string

The country related to the card

Example:
CYP
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/ff27b927-d346-4369-aba3-4478de764816/payment_methods HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "ff27b927-d346-4369-aba3-4478de764816",
            "name": "",
            "payment_method_type": "CARD",
            "is_primary": "true",
            "is_backup": "false",
            "notes": "Payment Method Notes",
            "settlement_account": [
                {
                    "name": "Primary Account",
                    "payment_gateway": {
                        "gateway": "JCC_MERCHANT",
                        "gateway_identifier": "1245"
                    }
                }
            ],
            "account_debit": {
                "account_name": "",
                "account_number": "001002001",
                "iban": "0143240434320434",
                "bank": "Barclays",
                "bank_code": "0032933-1123",
                "branch": "Ascot",
                "swift": "12345678",
                "sort_code": "20-02-53",
                "account_type": "SAVINGS",
                "mandate": {
                    "reference": "",
                    "sign_date": 1
                },
                "gateway_token": [
                    {
                        "token": "",
                        "gateway": "JCC",
                        "integration": {
                            "id": "",
                            "name": ""
                        }
                    }
                ]
            },
            "card": {
                "name": "Default Card",
                "brand": "VISA",
                "funding_type": "CREDIT",
                "first6": "",
                "last4": "",
                "expiration_month": 1,
                "expiration_year": 2020,
                "country_of_issue": "CYP",
                "cvc": "",
                "card_holder_details": {
                    "card_holder_name": "John Doe",
                    "address_line_1": "Elia Papakyriakou",
                    "address_line_2": "7 Tower Star",
                    "address_city": "Nicosia",
                    "address_zip": "2415",
                    "address_state": "Nicosia",
                    "address_country": "CYP"
                },
                "gateway_token": [
                    {
                        "token": "",
                        "gateway": "JCC_MERCHANT",
                        "integration": {
                            "id": "",
                            "name": ""
                        }
                    }
                ]
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Organisation Products

Disable Enable Products for an Organisation

GET /organisations/{id}/products
Get Products Availability
GET /organisations/{id}/products

Retrieve all products which are temporarily not available for sale for the specified organisation

Path variables

id
string GUID required

The organisation (identifier) whose product availability will be retrieved

Example:
52ed5363-e747-4f41-b91f-e6c5b5e32376

Request parameters

search_value
string optional

Search for a product using its SKU, its name or description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
product
Object

Defines the product of which availability is set

id
string GUID

The product identifier

Example:
c4301882-573a-f04c-7884-5228e7844981
sku
string

The product SKU

Example:
FE1234
name
string

The product name

Example:
Freddo Espresso
availability
string

Defines whether the product is available or not

Enumeration:
ENABLED
DISABLED
supply_method
Array

The supported supply method for the product

string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/52ed5363-e747-4f41-b91f-e6c5b5e32376/products HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "product": {
                "id": "c4301882-573a-f04c-7884-5228e7844981",
                "sku": "FE1234",
                "name": "Freddo Espresso"
            },
            "availability": "DISABLED",
            "supply_method": [
                "PICK_UP"
            ]
        }
    ]
}
Organisation Tags
POST /organisations/{id}/tags
PUT /organisation_tags/{id}
DELETE /organisation_tags/{id}
GET /organisation_tags
GET /organisation_tags/{id}
Add Organisation Tag
POST /organisations/{id}/tags

Create a new organisation tag

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The tag name

Example:
Restaurant

Responses

200 200

OK

Body
Object
id
string GUID

The tag identifier

Example:
178d86ab-3245-5b39-d145-f44e0ef61188
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/organisation_tags HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Restaurant"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "178d86ab-3245-5b39-d145-f44e0ef61188"
}
Update Organisation Tag
PUT /organisation_tags/{id}

Update a specific organisation tag

Path variables

id
string GUID required

The organisation tag (identifier) that will be updated

Example:
a3dedbef-89e1-5783-ad78-2f0c91086ca5

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The tag name

Example:
Restaurant

Responses

200 200

OK

Body
Object
id
string GUID

The tag identifier

Example:
178d86ab-3245-5b39-d145-f44e0ef61188
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/organisation_tags/a3dedbef-89e1-5783-ad78-2f0c91086ca5 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Restaurant"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "178d86ab-3245-5b39-d145-f44e0ef61188"
}
Delete Organisation Tag
DELETE /organisation_tags/{id}

Delete a specific organisation tag

Path variables

id
string GUID required

The organisation tag (identifier) that will be deleted

Example:
a3dedbef-89e1-5783-ad78-2f0c91086ca5

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/organisation_tags/a3dedbef-89e1-5783-ad78-2f0c91086ca5 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Organisation Tags
GET /organisation_tags

Search through all organisation tags

Request parameters

name
string optional

The organisation tag name

Example:
Restaurantt
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string GUID

The tag identifier

Example:
a3dedbef-89e1-5783-ad78-2f0c91086ca5
name
string

The tag name

Example:
Restaurant
owner
Object

Defines the organisation that owns the tag

id
string GUID

The organisation identifier

Example:
35f1b146-cb15-b5dd-763e-3f3be8b5a07e
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/organisation_tags HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "a3dedbef-89e1-5783-ad78-2f0c91086ca5",
            "name": "Restaurant"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Organisation Tag
GET /organisation_tags/{id}

Get details for a specific organisation tag

Path variables

id
string GUID required

The organisation tag (identifier) to be retrieved

Example:
03e80aae-3613-078c-1aa4-3130de25140a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The tag identifier

Example:
6ed98c88-ce30-b47d-0c75-dcfb8316c95a
name
string

The tag name

Example:
Restaurant
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/organisation_tags/03e80aae-3613-078c-1aa4-3130de25140a HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6ed98c88-ce30-b47d-0c75-dcfb8316c95a",
    "name": "Restaurant"
}
Reward Commercial Terms
PUT /organisations/{id}/reward_commercial_terms
GET /organisations/{id}/reward_commercial_terms
Update Reward Commercial Terms
PUT /organisations/{id}/reward_commercial_terms

Update the reward commercial terms for a specific organisation

Path variables

id
string GUID required

The organisation (identifier) that reward commercial terms will be set

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da

Notes

CORE BEHAVIOR

Reward Commercial Terms can be assigned only on Business and Merchant/Service Provider organisation types.
Only users of Business organisation types can amend Reward Commercial Terms related to their Business and Merchants/Service Providers.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
state
string nullable

Defines whether the organisation can contribute to the customers awards/spends

Enumeration:
BLOCKED
NOT_BLOCKED
reward_schemes
Array nullable

Defines the reward schemes that the organisation can contribute to the customers awards/spends

Unique items: YES
string GUID
Example:
7fdd1338-7064-4fe6-8f4f-0a02324d45c5
settlement_method
string nullable

Defines how the organisation will be settled

Enumeration:
ON_AWARD
ON_SPEND
Default:
ON_AWARD
default_contribution
number nullable

Defines the contribution fee that the organisation will cover on each award

Default:
100
Example:
99.99
explicit_contributions
Array nullable

Explicit contribution that will overwrite the default one

Object
type
string required

On which type the contribution will be applied

Enumeration:
REWARD_OFFER
id
string GUID required

The entity id on which the contribution will be applied

Example:
39081643-21b5-4782-a149-69a8bbc744be
contribution
number required

The explicitly defined contribution

Example:
49.99
purchases_restrictions
Object nullable

Details about customer purchase restrictions

max_purchases
integer nullable

The maximum number of purchases that a customer can submit in a day

Example:
12
max_purchase_amount
number nullable

The maximum purchase amount that a customer can submit

Example:
199.99

Responses

200 OK

Success

Body
Object
id
string GUID

The organisation identifier

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/organisations/7cc1b26a-459f-4b47-a09f-6b121ae947da/reward_commercial_terms HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "is_blocked": "false",
    "reward_schemes": [
        "7fdd1338-7064-4fe6-8f4f-0a02324d45c5"
    ],
    "management_fee": 99.99,
    "default_contribution": 99.99,
    "credit_expired_awards": "true",
    "explicit_contributions": [
        {
            "type": "REWARD_OFFER",
            "id": "39081643-21b5-4782-a149-69a8bbc744be",
            "contribution": 49.99
        }
    ],
    "customer_selfservice_purchases": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7cc1b26a-459f-4b47-a09f-6b121ae947da"
}
Get Reward Commercial Terms
GET /organisations/{id}/reward_commercial_terms

Returns the reward commercial terms of an organisation

Path variables

id
string GUID required

The organisation (identifier) whose reward commercial terms will be retrieved

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
state_details
Object

Details about the changes on the terms state

state
string

Defines whether the organisation can contribute to the customers awards/spends

Enumeration:
BLOCKED
NOT_BLOCKED
date
integer epoch

The date that the state has changed

Example:
1593607273
user
Object

The user that changed the state

id
string GUID

The user identifier

Example:
7454cc68-e855-4356-8984-377f8d77640a
name
string

The user name

Example:
John Doe
reward_schemes
Array

Defines the reward schemes that the organisation can contribute to the customers awards/spends

Example:
["7fdd1338-7064-4fe6-8f4f-0a02324d45c5"]
Object
id
string GUID

The reward scheme identifier

Example:
7fdd1338-7064-4fe6-8f4f-0a02324d45c5
name
string

The reward scheme name

Example:
CRM Loyalty
settlement_method
string

Defines how the organisation will be settled

Enumeration:
ON_AWARD
ON_SPEND
Default:
ON_AWARD
default_contribution
number

Defines the contribution fee that the organisation will cover on each award

Example:
99.99
explicit_contributions
Array

Explicit contribution that will overwrite the default one

Object
type
string

On which type the contribution will be applied

Enumeration:
REWARD_OFFER
id
string GUID

The entity id that the contribution will be applied

Example:
39081643-21b5-4782-a149-69a8bbc744be
name
string

The entity name that the contribution will be applied

Example:
1% cashback on all products
contribution
number

The explicitly defined contribution

Example:
49.99
purchases_restrictions
Object

Details about customer purchase restrictions

max_purchases
integer

The maximum number of purchases that a customer can submit in a day

Example:
1
max_purchase_amount
number

The maximum purchase amount that a customer can submit

Example:
9.01
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/7cc1b26a-459f-4b47-a09f-6b121ae947da/reward_commercial_terms HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "state_details": {
        "state": "NOT_BLOCKED",
        "date": 1593607273,
        "user": {
            "id": "7454cc68-e855-4356-8984-377f8d77640a",
            "name": "John Doe"
        }
    },
    "reward_schemes": [
        {
            "id": "7fdd1338-7064-4fe6-8f4f-0a02324d45c5",
            "name": "CRM Loyalty"
        }
    ],
    "settlement_method": "ON_SPEND",
    "default_contribution": 99.99,
    "explicit_contributions": [
        {
            "type": "REWARD_OFFER",
            "id": "39081643-21b5-4782-a149-69a8bbc744be",
            "name": "1% cashback on all products",
            "contribution": 49.99
        }
    ],
    "customer_selfservice_purchases": "true",
    "purchases_restrictions": {
        "max_purchases": 1,
        "max_purchase_amount": 9.01
    }
}
Transaction Acquiring Points
POST /organisations/{id}/taps
PUT /organisations/{id}/taps/{tap_id}
DELETE /organisations/{id}/taps/{tap_id}
GET /organisations/{id}/taps
GET /organisations/{id}/taps{tap_id}
Create Transaction Acquiring Point
POST /organisations/{id}/taps

Create a transaction acquiring point for an existing Organisation

Path variables

id
string GUID required

The organisation (identifier) on which a tap will be created

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object

Information about the organisation’s external references

name
string required

The transaction acquiring point name

Example:
POS
code
string nullable

The transaction acquiring point code

Example:
02451
is_active
boolean nullable

Defines whether the transaction acquiring point is active or not

Default:
true
Example:
true
description
string nullable

The transaction acquiring point description

Example:
pos system
external_ip
string nullable

IP address of External Device

Example:
82.102.93.164
external_port
string nullable

Port of the External IP

Example:
9100
tap_type
string required

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
string nullable

Optional specification of external reference

Enumeration:
JCC
TWINSOFT
ALOHA
WIFI_PLATFORM

Responses

200 200

OK

Body
Object
id
string GUID

The organisation’s transaction acquiring point identifier

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/taps HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "POS01",
    "value": "123456789",
    "is_active": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Transaction Acquiring Point
PUT /organisations/{id}/taps/{tap_id}

Update a transaction acquiring point for an existing Organisation

Path variables

id
string GUID required

The organisation’s transaction acquiring point (identifier) that will be updated

Example:
eff2bcf5-702d-ed03-ca12-f1ba8ac692a2
tap_id
string GUID required

The transaction acquiring point (identifier) that will be updated

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
code
string nullable

The transaction acquiring point code

Example:
123456789
is_active
boolean nullable

Determines whether the transaction acquiring point is active or not

Example:
true
description
string nullable

The transaction acquiring point description

Example:
pos system
external_ip
string nullable

IP address of External Device

Example:
82.102.93.164
external_port
string nullable

Port of the External IP

Example:
9100
tap_type
string nullable

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
string nullable

Optional specification of external reference

Enumeration:
JCC
TWINSOFT
ALOHA
WIFI_PLATFORM

Responses

200 200

OK

Body
Object
id
string GUID

The transaction acquiring point identifier

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/taps/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "value": "123456789",
    "is_active": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Transaction Acquiring Point
DELETE /organisations/{id}/taps/{tap_id}

Delete a transaction acquiring point for an existing organisation

Path variables

id
string GUID required

The organisation (identifier) whose tap will be deleted

Example:
eff2bcf5-702d-ed03-ca12-f1ba8ac692a2
tap_id
string GUID required

The transaction acquiring point (identifier) that will be deleted

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/taps/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Transaction Acquiring Points
GET /organisations/{id}/taps

Search transaction acquiring points for a specific organisation

Path variables

id
string GUID required

The organisation (identifier) whose transaction acquiring point will be retrieved

Example:
eff2bcf5-702d-ed03-ca12-f1ba8ac692a2

Request parameters

search_value
string optional

The value of the search (case insensitive) across Name, Code

Example:
1234345356543423234234
name
string optional

The transaction acquiring point name

Example:
POS
code
string optional

The transaction acquiring point code

Example:
P01
is_active
boolean optional

Filters transaction acquiring points whether are active or not

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object

Information about the organisation’s external references

id
string GUID

The transaction acquiring point identifier

Example:
TAP123456234567345674567895678IK
name
string

The transaction acquiring point name

Example:
ePOS
code
string

The transaction acquiring point code

Example:
EP12
is_active
boolean

Defines whether the transaction acquiring point is active or not

Example:
true
description
string

The transaction acquiring point description

Example:
electronic POS
external_ip
string

IP address of External Device

Example:
82.102.93.164
external_port
string

Port of the External IP

Example:
9100
tap_type
string

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
Object

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
GET https://devapi.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/taps HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "TAP1E31269B76D7A65ACCE45B2E68DFD",
            "name": "POS",
            "code": "P01",
            "is_active": "true",
            "description": "pos system"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
GET https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/taps?is_active=true HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "TAP1E31269B76D7A65ACCE45B2E68DFD",
            "name": "POS",
            "code": "P01",
            "is_active": "true",
            "description": "pos system",
            "external_ip": "82.102.93.164",
            "external_port": "9100",
            "tap_type": "GENERIC",
            "external_type": "STRIPE_MERCHANT"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Transaction Acquiring Point
GET /organisations/{id}/taps{tap_id}

Get details for a transaction acquiring point

Path variables

id
string GUID required

The organisation (identifier) whose transaction acquiring point will be retrieved

Example:
eff2bcf5-702d-ed03-ca12-f1ba8ac692a2
tap_id
string GUID required

The transaction acquiring point (identifier) that will be retrieved

Example:
c564e3ef-91f5-3aff-bfc9-263eb5954893

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object

Information about the organisation’s external references

id
string GUID

The transaction acquiring point identifier

Example:
TAP123456234567345674567895678IK
name
string

The transaction acquiring point name

Example:
ePOS
code
string

The transaction acquiring point code

Example:
EP12
is_active
boolean

Defines whether the transaction acquiring point is active or not

Example:
true
description
string

The transaction acquiring point description

Example:
electronic POS
external_ip
string

IP address of External Device

Example:
82.102.93.164
external_port
string

Port of the External IP

Example:
9100
tap_type
string

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
Object

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/tapsTAP1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": {
        "id": "TAP1E31269B76D7A65ACCE45B2E68DFD",
        "name": "POS",
        "code": "0012465",
        "is_active": "true",
        "description": "pos system",
        "external_ip": "82.102.93.164",
        "external_port": "9100",
        "tap_type": "POS"
    }
}
WiFi Network
POST /organisations/{id}/wifi/sites
GET /organisations/{id}/wifi/sites
POST /organisations/{id}/wifi/import
PUT /organisations/{id}/wifi/sites/{s_id}/networks
GET /organisations/{id}/wifi/sites/{s_id}/networks
PUT /organisations/{id}/wifi/sites/{s_id}/guest_control
GET /organisations/{id}/wifi/sites/{s_id}/guest_control
GET /organisations/{id}/wifi/sites/{s_id}/devices
Create WiFi Site
POST /organisations/{id}/wifi/sites

Path variables

id
string GUID required

The organisation (identifier) where a site will be created

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
integration_id
string GUID required

The WiFi platform integration

Example:
c6932bcf-b7e8-4fcc-b168-85ea400fb8ed
site_id
string required

The organisation site identifier as provided from WiFi platform

Example:
88quh2m6

Responses

200 OK
Body
Object
id
string GUID

The organisation network site identifier

Example:
0633ab11-9090-001c-5998-936ae44ff5e0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "integration_id": "c6932bcf-b7e8-4fcc-b168-85ea400fb8ed",
    "site_id": "88quh2m6"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0633ab11-9090-001c-5998-936ae44ff5e0"
}
List WiFi Sites
GET /organisations/{id}/wifi/sites

Retrieve all network sites for an organisation

Path variables

id
string GUID required

The organisation (identifier) whose sites will be retrieved

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f

Request parameters

integration_id
string GUID optional

Filter based on integration

Example:
f649fe38-bd59-246a-2322-60fa4f1a1c3d

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The site identifier

Example:
21f8a49e-b0c3-0334-b708-b2ef9cac8adb
integration
Object

Details about the integration

id
string GUID

The integration identifier

Example:
81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4
name
string

The integration name

Example:
UniFi
site_id
string

The WiFi platform site id

Example:
88quh2m6
guest_control
Object

Details about the guest control settings

redirect_url
string

Defines the redirection URL (landing page) that contacts will access when joining a guest wifi network

Example:
https://crm.com/landing-page
wifi_networks
Array

Details about the wifi networks related to the site

Object
id
string

The network identifier

Example:
619387ec31d36b2cf6f9d8af
name
string

the network name

Example:
CRM-Nicosia
is_enabled
boolean

Defines whether the network is enabled or not

Example:
true
is_guest_enabled
boolean

Defines whether the guest access is enabled or not

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "21f8a49e-b0c3-0334-b708-b2ef9cac8adb",
            "integration": {
                "id": "81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4",
                "name": "UniFi"
            },
            "site_id": "88quh2m6"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Import WiFi Data
POST /organisations/{id}/wifi/import

Retrieve WiFi data for a specific organisation from a WiFi platform

Path variables

id
string GUID required

The organisation (identifier) that WiFi data will be imported

Example:
5e4f4825-b378-d856-c393-1cf3fde458dd

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
site_id
string required

The external reference of the organisation over to the WiFi platform

Example:
wer232rw
type
string required

Defines which data should be imported

Enumeration:
DEVICES
WIFI_NETWORKS
GUEST_CONTROL

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The organisation identifier

Example:
5e4f4825-b378-d856-c393-1cf3fde458dd
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/5e4f4825-b378-d856-c393-1cf3fde458dd/wifi/import HTTP/1.1 

Content-Type: application/json

{
    "site_id": "wer232rw",
    "type": "DEVICES"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "5e4f4825-b378-d856-c393-1cf3fde458dd"
}
Update WiFi Networks
PUT /organisations/{id}/wifi/sites/{s_id}/networks

Update a WiFi network for an organisation

Path variables

id
string GUID required

The organisation (identifier) whose networks will be updated

Example:
add25d0e-54fc-c005-ca5e-60f167c35578
s_id
string GUID required

The site (identifier) of which networks will be updated

Example:
02b80141-8b0a-9803-0762-b76e50d34e9e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
id
string GUID

The network (identifier) that will be updated

Example:
fecbacb3-0a03-219a-b86c-6a3b31032410
name
string

The network name that will be updated

Example:
ARRIS012
is_enabled
boolean

Defines whether the network is enabled or not

Example:
true
is_guest_enabled
boolean

Defines whether the network has enabled the guest access or not

Example:
false

Responses

200 OK
Body
Object
id
string GUID

The organisation identifier

Example:
add25d0e-54fc-c005-ca5e-60f167c35578
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/organisations/add25d0e-54fc-c005-ca5e-60f167c35578/wifi/sites/02b80141-8b0a-9803-0762-b76e50d34e9e/networks HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

[
    {
        "network_id": "fecbacb3-0a03-219a-b86c-6a3b31032410",
        "is_enabled": "true",
        "is_guest_enabled": "false"
    }
]

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "add25d0e-54fc-c005-ca5e-60f167c35578"
}
Get WiFi Networks
GET /organisations/{id}/wifi/sites/{s_id}/networks

Retrieve an organisation’s supported networks

Path variables

id
string GUID required

The organisation (identifier) of which networks will be retrieved

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f
s_id
string GUID required

The site (identifier) of which networks will be retrieved

Example:
02b80141-8b0a-9803-0762-b76e50d34e9e

Request parameters

is_enabled
boolean optional

Filters based on whether the network is enabled or not

Example:
true
is_guest_enabled
boolean optional

Filters based on whether the network has enabled the guest access or not

Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The network identifier

Example:
619387ec31d36b2cf6f9d8af
name
string

The network name

Example:
CRM-Nicosia
is_enabled
boolean

Defines whether the network is enabled or not

Example:
true
is_guest_enabled
boolean

Defines whether the network has enabled the guest access or not

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites/02b80141-8b0a-9803-0762-b76e50d34e9e/networks HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "619387ec31d36b2cf6f9d8af",
            "name": "CRM-Nicosia",
            "is_enabled": "true",
            "is_guest_enabled": "false"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Update Guest Control
PUT /organisations/{id}/wifi/sites/{s_id}/guest_control

Update an organisation’s guest control settings

Path variables

id
string GUID required

The organisation (identifier) whose guest control will be updated

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f
s_id
string GUID required

The site (identifier) of which guest control will be updated

Example:
85b8181b-a1f2-8642-2400-3f9476bfc031

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
redirect_url
string required

Defines the redirection URL (landing page) that contacts will access when joining a guest wifi network

Example:
https://crm.com/;anding-page

Responses

200 OK
Body
Object
id
string GUID

The organisation network site identifier

Example:
0633ab11-9090-001c-5998-936ae44ff5e0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites/85b8181b-a1f2-8642-2400-3f9476bfc031/guest_control HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "redirect_url": "https://crm.com/;anding-page"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0633ab11-9090-001c-5998-936ae44ff5e0"
}
Get WiFi Guest Control
GET /organisations/{id}/wifi/sites/{s_id}/guest_control

Retrieve guest control settings for an organisation

Path variables

id
string GUID required

The organisation (identifier) of which guest control will be retrieved

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f
s_id
string GUID required

The site (identifier) of which guest control will be retrieved

Example:
5464d7c1-8bb4-357c-33de-3e0059c6b984

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
redirect_url
string

Defines the redirection URL (landing page) that contacts will access when joining a guest wifi network

Example:
https://crm.com/landing-page
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites/5464d7c1-8bb4-357c-33de-3e0059c6b984/guest_control HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "redirect_url": "https://crm.com/landing-page"
}
Get WiFi Devices
GET /organisations/{id}/wifi/sites/{s_id}/devices

Retrieve devices (access points) from WiFi network for a specific organisation

Path variables

id
string GUID required

The organisation (identifier) of which devices will be retrieved

Example:
35b9bc9c-466b-de7a-f23b-ed7a227e309f
s_id
string GUID required

The site (identifier) of which devices will be retrieved

Example:
7ae2d47f-39ca-377f-66c1-4f707795b7e3

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array

The organisation identifier

Object
name
string

The device name

Example:
CRM-Nicosia
mac-address
string

The device mac address

Example:
00:00:5e:00:53:af
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/35b9bc9c-466b-de7a-f23b-ed7a227e309f/wifi/sites/7ae2d47f-39ca-377f-66c1-4f707795b7e3/devices HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "CRM-Nicosia",
            "mac-address": "00:00:5e:00:53:af"
        }
    ]
}
Communications
POST /communications
GET /communications/{id}
GET /communications
Create Communication
POST /communications

Creates a single communication for a speciifc Contact

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
name
string

The name of the communication

Example:
Happy Birthday
contact_id
string GUID required

The GUID of the Contact that the communication will be sent to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
channel
string required

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
integration_id
string GUID required

The integration that will send the communication

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
language
string

The language of the communication

Example:
ENG
recipient
string

The recipient’s address or phone according to the channel

Example:
customer@crm.com
title
string

Title of push notification (applicable for INAPP channels)

Example:
New Festive Beverages
subtitle
string

Subtitle (iOS only) of push notification (applicable for INAPP channels)

Example:
20% discount for December
subject
string

The actual subject of the communication sent (applicable for EMAIL channels)

Example:
New Rewards Offer
content
string

The actual content of the communication sent

ignore_preferences
boolean

If set to True then the email and sms opt-out preferences of contact will be ignored

Default:
false
Example:
true
in_app_image_url
string

Image for push notification

in_app_click_link_url
string

Push notification URL (deep linking)

message_type
string nullable

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/communications HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "Happy Birthday",
    "contact_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "channel": "EMAIL",
    "integration_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "language": "ENG",
    "recipient": "customer@crm.com",
    "title": "New Festive Beverages",
    "subtitle": "20% discount for December", 
    "subject": "New Rewards Offer",
    "content": "",
    "ignore_preferences": "true",
    "in_app_image_url": "",
    "in_app_click_link_url": "",
    "message_type": "OSD"
}
Get Communication
GET /communications/{id}

Retrieve a specific communication

Path variables

id
string GUID required

The ID of the communication to be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

The request has succeeded

Body
application/json
Object
name
string

The name of the communication

Example:
Happy Birthday
life_cycle_state
string

The state of the communication

Enumeration:
PENDING
COMPLETED
REJECTED
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
is_viewed
boolean

Has the recipient viewed the communication?

Example:
false
viewed_on
integer epoch

The datetime that the recipient viewed the communication

Example:
1583846861
is_archived
boolean

Has the recipient archived the communication?

Example:
true
clicked_on
integer epoch

The date links in the communication where first clicked by the recipient

Example:
1583846865
created_on
integer epoch

The date and time that the communication was created

Example:
1583846861
language
string

The language of the communication

Example:
ENG
sender
string

The default sender

Example:
dev@crm.com
recipient
string

The email or number of the recipient

Example:
jon@crm.com
title
string

Title of push notification (applicable for INAPP channels)

Example:
New Festive Beverages
subtitle
string

Subtitle (iOS only) of push notification (applicable for INAPP channels)

Example:
20% discount for December
subject
string

The actual subject of the communication sent (if applicable)

content
string

The actual content of the communication sent

in_app_image_url
string

Image for push notification

in_app_click_link_url
string

Push notification URL (deep linking)

contact
Object

The contact that the communication was delivered to

id
string GUID

The unique identifier of the contact

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The full name of the contact

Example:
John Johnson
code
string

The unique code of the contact

Example:
C123
message_type
string

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/communications/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Happy Birthday",
    "life_cycle_state": "PENDING",
    "channel": "EMAIL",
    "is_viewed": true,
    "viewed_on": 1583846861,
    "is_archived": true,
    "clicked_on": 1583846865,
    "created_on": 1583846861,
    "language": "ENG",
    "sender": "dev@crm.com",
    "recipient": "jon@crm.com",
    "subject": "",
    "content": "",
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    }
}
List Communications
GET /communications

Retrieves all available communications

Request parameters

contact_id
string GUID optional

The contact ID for which the communications will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
life_cycle_state
string optional

The life cycle state of the communications to be retrieved

Enumeration:
PENDING
COMPLETED
REJECTED
channel
string optional

The channel of the communications to be retrieved

Enumeration:
SMS
EMAIL
DEVICE
INAPP
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
application/json
Object
content
Array
Object
id
string GUID

The communication ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the communication plan in case this communication was created based on a plan

Example:
Happy Birthday
life_cycle_state
string

The state of the communication

Enumeration:
PENDING
COMPLETED
REJECTED
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
is_viewed
boolean

Has the recipient viewed the communication?

Example:
false
viewed_on
integer epoch

The datetime that the recipient viewed the communication

Example:
1583846865
is_archived
boolean

Has the recipient archived the communication?

clicked_on
integer epoch

The date links in the communication where first clicked by the recipient

Example:
1583846865
created_on
integer epoch

The date and time that the communication was created

Example:
1583846865
language
string

The communication’s language

Example:
ENG
sender
string

The default sender

Example:
dev@crm.com
recipient
string

The email or number of the recipient

Example:
jon@crm.com
subject
string

The actual subject of the communication sent (if applicable)

Example:
Welcome to our company
content
string

The actual content of the communication sent

Example:
Dear sir/madam...
title
string

Title of push notification (applicable for INAPP channels)

Example:
New Festive Beverages
subtitle
string

Subtitle (iOS only) of push notification (applicable for INAPP channels)

Example:
20% discount for December
in_app_image_url
string

Image for push notification

in_app_click_link_url
string

Push notification URL (deep linking)

contact
Object

The contact that the communication was delivered to

id
string GUID

The unique identifier of the contact

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The full name of the contact

Example:
John Smith
code
string

The unique code of the contact

Example:
H8893M70
message_type
string

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/communications HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Happy Birthday",
            "life_cycle_state": "PENDING",
            "channel": "EMAIL",
            "is_viewed": true,
            "viewed_on": 1583846865,
            "is_archived": true,
            "clicked_on": 1583846865,
            "created_on": 1583846865,
            "language": "ENG",
            "sender": "dev@crm.com",
            "recipient": "jon@crm.com",
            "subject": "Welcome to our company",
            "content": "Dear sir/madam...",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "in_app_image_url": "",
            "in_app_click_link_url": "",
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Smith",
                "code": "H8893M70"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Communication Templates
POST /communication_templates
PUT /communication_templates/{id}
GET /communication_templates
GET /communication_templates/{id}
DELETE /communication_templates/{id}
POST /printout
Create Communication Template
POST /communication_templates

Creates a communication template

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
name
string required

The name of the communication template

Example:
New Rewards Offer Template
entity
string

Communication template related entity

Enumeration:
INVOICE
ORDERS
PAYMENT
CREDIT_NOTE
REFUND
PAYOUT
SERVICE_REQUEST
channel
string

Channel of communication - subject to integrations

Example:
SMTP
contents
Array
Object
language
string

The language that the content is provided in (3-digits)

Example:
ENG
title
string

Title - applicable if template is for push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle - applicable if template is for push notifications

Example:
20% discount for December
subject
string

The subject of the communication of the rich content

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Type of image

Enumeration:
UPLOAD
URL
Example:
UPLOAD
in_app_click_link_url
string

Push notification URL (deep linking)

is_default
boolean required

Defines whether the communication template is the default one

Example:
true

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication template identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/communication_templates HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "New Rewards Offer Template",
    "entity": "INVOICE",
    "channel": "SMTP",
    "contents": [
        {
            "language": "ENG",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "subject": "",
            "rich_content": "",
            "plain_content": "",
            "in_app_image_url": "",
            "in_app_image_type": "UPLOAD",
            "in_app_click_link_url": ""
        }
    ]
}
Update Communication Template
PUT /communication_templates/{id}

Update a communication template

Path variables

id
string required

The communication template identifier to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
id
string required

Communication template unique id

Example:
e82c88c8-0c5a-4fc9-97fc-06bed0506578
name
string required

The name of the communication template

Example:
General invoice
contents
Array
Object
id
string required

Communication template content id

Example:
db56a528-fe5a-49d0-8424-87f76caee81a
language
string

The language that the content is provided in (3-digits)

Example:
ENG
title
string

Title - applicable if template is for push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle - applicable if template is for push notifications

Example:
20% discount for December
subject
string

The subject of the communication of the rich content

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Type of image

Enumeration:
UPLOAD
URL
Example:
UPLOAD
in_app_click_link_url
string

Push notification URL (deep linking)

is_default
boolean nullable

Defines whether the communication template is the default one

Example:
false

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication template identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/communication_templates/{id} HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "id": "e82c88c8-0c5a-4fc9-97fc-06bed0506578",
    "name": "General invoice",
    "contents": [
        {
            "id": "db56a528-fe5a-49d0-8424-87f76caee81a",
            "language": "ENG",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "subject": "",
            "rich_content": "",
            "plain_content": "",
            "in_app_image_url": "",
            "in_app_image_type": "UPLOAD",
            "in_app_click_link_url": ""
        }
    ]
}
List Communication Templates
GET /communication_templates

Retrieves all available communication templates

Request parameters

entity
string optional

The communication template related entity

Enumeration:
INVOICE
ORDERS
PAYMENT
CREDIT_NOTE
REFUND
PAYOUT
SERVICE_REQUEST
channel
string optional

Channel of communication - subject to integrations

Enumeration:
EMAIL
SMS
INAPP
DEVICE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
name
string optional

Retrieves the communication templates based on their names

Example:
New Rewards Offer Template

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
application/json
Object
content
Array
Object
id
string

Unique id of communication template

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The name of the communication template

Example:
New Rewards Offer Template
entity
string

Communication template related entity

Enumeration:
INVOICE
ORDERS
PAYMENT
CREDIT_NOTE
REFUND
PAYOUT
SERVICE_REQUEST
channel
string

Channel of communication

Example:
SMS
is_default
string

Defines whether the communication template is the default one

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/communication_templates HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "name": "New Rewards Offer Template",
            "entity": "INVOICE",
            "channel": "SMS"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Communication Template
GET /communication_templates/{id}

Retrieve a single communication template

Path variables

id
string GUID required

The communication template id

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string

Communication template unique id

Example:
e82c88c8-0c5a-4fc9-97fc-06bed0506578
name
string required

The name of the communication template

Example:
New Rewards Offer Template
entity
string

Communication template related entity

Enumeration:
INVOICE
ORDERS
PAYMENT
CREDIT_NOTE
REFUND
PAYOUT
SERVICE_REQUEST
channel
string

Channel of communication

Example:
EMAIL
contents
Array
Object
id
string

Communication template content id

Example:
db56a528-fe5a-49d0-8424-87f76caee81a
language
string

The language that the content is provided in (3-digits)

Example:
ENG
title
string

Title - provided if template is for push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle (iOS only) - provided if template is for push notifications

Example:
20% discount for December
subject
string

The subject of the communication of the rich content

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Type of image

Enumeration:
UPLOAD
URL
Example:
UPLOAD
in_app_click_link_url
string

Push notification URL (deep linking)

is_default
boolean

Defines whether the communication template is the default one

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/communication_templates/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "e82c88c8-0c5a-4fc9-97fc-06bed0506578",
    "name": "New Rewards Offer Template",
    "entity": "INVOICE",
    "channel": "EMAIL",
    "contents": [
        {
            "id": "db56a528-fe5a-49d0-8424-87f76caee81a",
            "language": "ENG",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "subject": "",
            "rich_content": "",
            "plain_content": "",
            "in_app_image_url": "",
            "in_app_image_type": "UPLOAD",
            "in_app_click_link_url": ""
        }
    ]
}
Delete Communication Template
DELETE /communication_templates/{id}

Delete a communication template

Path variables

id
string GUID required

The communication template id to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Printout
POST /printout

Use this API to send a transaction as an email or view it as a web page (to print), the output is based on a configured communication template which must be specified.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
entity
Object

Details of entity to be output

name
string

Output entity type

Enumeration:
INVOICE
ORDERS
PAYMENT
CREDIT_NOTE
REFUND
PAYOUT
SERVICE_REQUEST
id
string

Output entity id (e.g. invoice id)

Example:
007c08166f95-8c54d563-b991-4b76-8a83
template_id
string

Communication template id to be used for output

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
action
string

Output type

Enumeration:
EMAIL

Transaction is sent to the Contact’s email address

WEB_VIEW

Transaction is viewed as a web page (can be printed using web browser)

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication template identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/printout HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "entity": {
        "name": "INVOICE",
        "id": "007c08166f95-8c54d563-b991-4b76-8a83"
    },
    "template_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "action": "EMAIL"
}
Communication Plans
POST /communication_plans
PUT /communication_plans/{id}
DELETE /communication_plans/{id}
GET /communication_plans
GET /communication_plans/{id}
Create Communication Plan
POST /communication_plans

Creates a single communication plan

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
name
string

The communication plan’s name

Example:
New Reward Offers
end_date
integer epoch

The datetime that the communication plan ends running

Example:
12345678
start_date
integer epoch required

The datetime that the communication plan will start running

Example:
12345678
segments
Array

A list of segments that the communications will be sent to

string GUID

the segment ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
contents
Array

A list of communication contents set up based on the channels and languages enabled

Object

the IDs of different contents used in this communication plan. Different languages and type of text

language
string

The language that the content is provided in (3-digitis)

Example:
ENG
title
string

Title for INAPP push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle for INAPP push notifications (iOS only)

Example:
20% discount for December
subject
string

The subject of the communication of the rich content (not for INAPP)

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Type of image

Enumeration:
UPLOAD
URL
in_app_click_link_url
string

Push notification URL (deep linking)

integrations
Array

A list of integrations that will send the emails. One integration/connector per channel should be provided

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
message_type
string required nullable

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
life_cycle_state
string

The life cycle state of the Communication Plan

Enumeration:
DRAFT
POSTED

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication plan identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/communication_plans HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "New Reward Offers",
    "end_date": 12345678,
    "start_date": 12345678,
    "preferred_channel": "WHATSAPP",
    "segments": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "contents": [
        {
            "language": "ENG",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "subject": "",
            "rich_content": "",
            "plain_content": "",
            "in_app_image_url": "",
            "in_app_image_type": "UPLOAD",
            "in_app_click_link_url": ""
        }
    ],
    "integrations": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "frequency": "0 0 12 * * ?",
    "life_cycle_state": "POSTED"
}
Update Communication Plan
PUT /communication_plans/{id}

Updates an existing communication plan

Path variables

id
string GUID required

The ID of the communication plan to be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
name
string nullable

The communication plan’s name

Example:
New Reward Offer
start_date
integer epoch required

The datetime that the communication plan will start running

Example:
112345678
end_date
integer epoch required

The datetime that the communication plan ends running

Example:
12345678
segments
Array

A list of segments that the communications will be sent to

string GUID

the segment ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
contents
Array

A list of communication contents set up based on the channels and languages enabled

Object

the IDs of different contents used in this communication plan. Different languages and type of text

language
string

The language that the content is provided in (3-digitis)

Example:
ENG
title
string

Title for INAPP push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle for INAPP push notifications (iOS only)

Example:
20% discount for December
subject
string

The subject of the communication of the rich content (not for INAPP)

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Image type

Enumeration:
UPLOAD
URL
Example:
UPLOAD
in_app_click_link_url
string

Push notification URL (deep linking)

integrations
Array

A list of integrations that will send the emails. One integration/connector per channel should be provided

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
message_type
string required nullable

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
life_cycle_state
string

The life cycle state of the Communication Plan

Enumeration:
DRAFT
POSTED

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The communication plan identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/communication_plans/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "New Reward Offer",
    "end_date": 12345678,
    "start_date": 112345678,
    "preferred_channel": "SMS",
    "segments": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "contents": [
        {
            "language": "ENG",
            "title": "New Festive Beverages",
            "subtitle": "20% discount for December",
            "subject": "",
            "rich_content": "",
            "plain_content": "",
            "in_app_image_url": "",
            "in_app_image_type": "UPLOAD",
            "in_app_click_link_url": ""
        }
    ],
    "integrations": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "frequency": "0 0 12 * * ?",
    "life_cycle_state": "DRAFT"
}
Delete Communication Plan
DELETE /communication_plans/{id}

Deletes a single communication plan

Path variables

id
string GUID required

The ID of the communication plan to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/communication_plans/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 
List Communication Plans
GET /communication_plans

Retrieves all available communication plans

Request parameters

search_value
string optional

The value of the search across the plan name

Example:
New Offer
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
application/json
Object
content
Array
Object
id
string GUID

The communication plan identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The communication plan name

Example:
New Reward Offers
start_date
integer epoch

The datetime that the communication plan will start running

Example:
12345678
end_date
integer epoch

The datetime that the communication plan ends running

Example:
12345678
life_cycle_state
string

The life cycle state of the Communication Plan

Enumeration:
DRAFT
POSTED
integrations
Object
id
string GUID

The integration identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the integration

Example:
Connection for Emails
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
owner
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/communication_plans HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "New Reward Offers",
            "end_date": 12345678,
            "start_date": 12345678
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Communication Plan
GET /communication_plans/{id}

Retrieves a specific communication plan

Path variables

id
string GUID required

The unique ID of the communication plan to be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
application/json
Object
name
string

The name of the communication plan

Example:
New Rewards Offer
end_date
integer epoch

The datetime that the communication plan ends running

Example:
12345678
start_date
integer epoch required

The datetime that the communication plan will start running

Example:
12345678
segments
Array

A list of segments that the communications will be sent to

Object

the segment ID

id
string GUID

The ID of the segment

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the segment

Example:
VIP Contacts
contents
Array

A list of communication contents set up based on the channels and languages enabled

Object

the IDs of different contents used in this communication plan. Different languages and type of text

language
string

The language that the content is provided in (3-digits)

Example:
ENG
title
string

Title for INAPP push notifications

Example:
New Festive Beverages
subtitle
string

Subtitle for INAPP push notifications (iOS only)

Example:
20% discount for December
subject
string

The subject of the communication of the rich content (not for INAPP)

rich_content
string

The content in rich format

plain_content
string

The content in plain format

in_app_image_url
string

Image for push notification

in_app_image_type
string

Type of image

Enumeration:
UPLOAD
URL
Example:
UPLOAD
in_app_click_link_url
string

Push notification URL (deep linking)

integrations
Array

A list of integrations that will send the communications. One integration/connector per channel should be provided

Object
id
string GUID

The unique identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the integration

Example:
Connection for Emails
channel
string

The channel that the communication is sent through

Enumeration:
SMS
EMAIL
DEVICE
INAPP
frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
message_type
string

The message type that a provisioning provider will send (applicable and required only if the selected integrator is a provisioning provider)

Enumeration:
MAIL

Email Communication (send by provisioning provider)

OSD

On Screen Display Communication (send by provisioning provider)

life_cycle_state
string

The life cycle state of the Communication Plan

Enumeration:
DRAFT
POSTED
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/communication_plans/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 
Contacts
POST /contacts
PUT /contacts/{id}
GET /contacts
GET /customers
GET /contacts/{id}
DELETE /contacts/{id}
Create Contact
POST /contacts

Create a new contact (person or company)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
id
string GUID nullable

The contact identifier. if not supplied one will be generated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string nullable

User readable code for the contact

Example:
0010202311
contact_type
string required

Type of contact support types include Person and Company.

Enumeration:
PERSON
COMPANY
is_tax_exempt
boolean nullable

Defines whether the contatc is classified as Tax Exempt or not. Defaults to False.

Default:
false
Example:
false
company_name
string required nullable

Company Name if the Contact represents a company, required attribute if the type is a Company.

Example:
Good Burger
title
string

The title of the contact. Applicable only if the type is PERSON

Example:
Sir
first_name
string required nullable

The first name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Louis
middle_name
string nullable

The middle name of the contact. Applicable only if the type is PERSON

Example:
Aloz
last_name
string required nullable

The last name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Kozior
preferred_language_code
string

The contact’s preferred language for communication

Example:
ENG
statutory_number
string

The contact’s unique statutory number

Example:
231224-1222000
notes
string

Notes for the contact

Example:
Notes
sms_opt_out
boolean nullable

The contact setting for receiving sms. Default value is false

Example:
true
email_opt_out
boolean nullable

The contact setting for receiving emails. Default value is false

Example:
false
create_default_account
boolean

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.

Example:
true
category_id
string

The contact’s category.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
email_address
string

The contact’s email address

Example:
bill@gmail.com
referral_code
string nullable

The contact’s referral code

Example:
REF123
loyalty_identifier
string nullable

The contact’s loyalty identifier

Example:
1234567897415
country_agreement
string nullable

The country code that the contact agreed to register to

Example:
CYP
demographics
Object nullable

Information about the contact’s demographic. Applicable only if the contact type is PERSON

gender
string nullable

The gender of the contact

Enumeration:
MALE
FEMALE
country_of_residence
string nullable

The country code for the country of residence

Example:
USA
passport
Object nullable

Information about the contact’s passport

passport_number
string required

The passport number

Example:
K)123456
issue_country_code
string required

The passport’s issue country code

Example:
GRC
expiration_date
integer epoch required

The passport’s expiration date

Example:
13423423222
id_details
Object nullable

Information about the contact’s id. Applicable only if the contact is type of PERSON

id_number
string required

The id number

Example:
132465
issue_country_code
string required

The id’s issue country code

Example:
CYP
expiration_date
integer epoch required

The id’s expiration date

Example:
1129876567
name_day
Object nullable

The contact’s name day. Applicable only if the contact is type of PERSON

month
integer required

The month of the name day

Example:
4
day
integer required

The day of the name day

Example:
12
date_of_birth
Object nullable

Information about the contact’s data of birth. Applicable only if the contact is type of PERSON

year
integer required

The birth year

Example:
1999
month
integer required

The birth month

Example:
12
day
integer required

The birth day

Example:
31
company_profile
Object nullable

Information about the company’s profile. Applicable only if contact_type is COMPANY

industry_id
string GUID nullable

The company’s industry unique ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
profile_year
integer nullable

The profile year

Example:
2019
annual_turnover
integer nullable

The annual turnover

Example:
450000
established_on
integer epoch nullable

The date that the company was established on

Example:
98765342
number_of_employees
integer nullable

The company’s number of employees

Example:
200
registration_number
string nullable

The company’s registration number

Example:
123456
registration_country
string nullable

The company’s registrationc country code

Example:
CYP
tax_reference_number
string nullable

The company’s tax reference number

Example:
TAX1234
vat_registration_number
string nullable

The company VAT registration numnber

Example:
VAT1234
industry_sectors
Array nullable

The company’s industry sectors IDs

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
addresses
Array nullable

Information about the contact’s addresses

Object

Information about an address of the contact

address_type
string required

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string nullable

A short name to allow it to be easily recognised in a list

Example:
My sister's house
is_primary
boolean nullable

Defines whether the address is the primary one (used for billing or communication purposes)

Default:
false
Example:
true
address_line_1
string required

The address line 1 (main address information

Example:
Elia Papakyriakou
address_line_2
string nullable

The address line 2 (additional information)

Example:
7 Tower Stars
state_province_county
string nullable

The address state/province/county

Example:
Egkomi
town_city
string nullable

The address town/city

Example:
Nicosia
postal_code
string nullable

The address postal code

Example:
2000
country_code
string required

The address country code (3 char code based)

Example:
CYP
lat
number nullable

The latitude of the address

Example:
35.157115
lon
number nullable

The longitude of the address

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string nullable

The address care of

Example:
n/a
phones
Array
Object
is_primary
boolean
Example:
true
country_code
string
Example:
CYP
number
string
Example:
238065437
phone_type
string
Enumeration:
LANDLINE
MOBILE
FAX
accounts
Array

Optional basic account settings for a financial contact

Object
name
string

The account name

Example:
AR001
is_primary
boolean

Indicates the primary account of the contact

Example:
true
credit_limit
number

The account credit limit

Example:
250.12
currency_code
string

The account currency

Example:
GBP
classification_id
string GUID

The account classification identifier

Example:
356215f1-8775-c949-cc18-b6da670d319a
payment_terms_id
string

The account’s payment terms

Example:
356215f1-8775-c949-cc18-b6da670d319a
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Create a contact for a person

POST https://sandbox.crm.com/backoffice/v1/contacts HTTP/1.1 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "0010202311",
    "contact_type": "COMPANY",
    "is_tax_exempt": "false",
    "company_name": "Good Burger",
    "title": "Sir",
    "first_name": "Louis",
    "middle_name": "Aloz",
    "last_name": "Kozior",
    "preferred_language_code": "ENG",
    "statutory_number": "231224-1222000",
    "notes": "Notes",
    "sms_opt_out": "true",
    "email_opt_out": "false",
    "create_default_account": true,
    "category_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "email_address": "bill@gmail.com",
    "referral_code": "REF123",
    "loyalty_identifier": "1234567897415",
    "country_agreement": "CYP",
    "demographics": {
        "gender": "MALE",
        "country_of_residence": "USA",
        "passport": {
            "passport_number": "K)123456",
            "issue_country_code": "GRC",
            "expiration_date": 13423423222
        },
        "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
        }
    },
    "company_profile": {
        "industry_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "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",
        "industry_sectors": [
            "CAD1E31269B76D7A65ACCE45B2E68DFD"
        ]
    },
    "addresses": [
        {
            "address_type": "BUSINESS",
            "address_name": "My sister's house",
            "is_primary": "true",
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2000",
            "country_code": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
            "care_of": "n/a"
        }
    ],
    "phones": [
        {
            "is_primary": true,
            "country_code": "CYP",
            "number": "238065437",
            "phone_type": "MOBILE"
        }
    ],
    "accounts": [
        {
            "name": "AR001",
            "is_primary": true,
            "credit_limit": 250.12,
            "currency_code": "GBP",
            "classification_id": "356215f1-8775-c949-cc18-b6da670d319a",
            "payment_terms_id": "356215f1-8775-c949-cc18-b6da670d319a"
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Contact
PUT /contacts/{id}

Update a Contact, it is possible to supply a partial body so that only supplied items will be updated.

Path variables

id
string required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
company_name
string

Company Name if the Contact represents a company, required attribute if the type is a Company.

Example:
Good Burger
title
string

The title of the contact. Applicable only if the type is PERSON

Example:
Sir
first_name
string

The first name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Louis
middle_name
string

The middle name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Aloz
last_name
string

The last name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Kozior
preferred_language_code
string

The preferred language for the contact (used on communications, translations, etc)

Example:
ENG
category_id
string

The contact’s category

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
notes
string

Notes for the contact

Example:
Notes
statutory_number
string

The contact’s statutory number

Example:
EF12345
demographics
Object

A person’s demographic details (applicable only if contact type is PERSON)

gender
string

The gender of the contact

Enumeration:
MALE
FEMALE
country_of_residence
string
passport
Object
passport_number
string
issue_country_code
string
Example:
GRC
expiration_date
integer
Example:
129876567
id_details
Object
id_number
string
isssue_country_code
string
Example:
CYP
expiration_date
integer
name_day
Object
month
integer
Example:
10
day
integer
Example:
4
date_of_birth
Object
year
integer
Example:
2018
month
integer
Example:
10
day
integer
Example:
16
company_profile
Object

A company’s profile (applicable only if contact type is COMPANY)

industry_id
string GUID

The company’s Industry ID

Example:
4AD9C84FA60F9FE407140E20F707726A
profle_year
number
annual_turnover
number
established_on
integer
number_of_employees
number
registration_number
string
registration_country
string
tax_reference_number
string
vat_registration_number
string
industry_sectors
Array

The company’s Industry Sectors.

string GUID
Example:
4AD9C84FA60F9FE407140E20F707726A
phones
Array

A list of phones that should be set on the contact

Object
id
string
is_primary
boolean
Example:
true
country_code
string
Example:
44
number
string
Example:
238065437
phone_type
string
Enumeration:
LANDLINE
MOBILE
FAX
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
email_address
string

The contact’s email address

Example:
bill@gmail.com
sms_opt_out
boolean

The contact setting for receiving sms.

email_opt_out
boolean

The contact setting for receiving emails.

is_tax_exempt
boolean

Defines whether the contact is tax exempt or not

Example:
false
addresses
Array
Object
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string
Example:
My sister's house
is_primary
string
Example:
true
address_line_1
string
address_line_2
string
Example:
Thomas V
state_province_county
string
Example:
Active
town_city
string
postal_code
string
country_code
string
Example:
CYP
lat
string
lon
string
google_place_id
string
is_billing
boolean
Example:
true

Responses

200 200

OK

Body
Object
id
string GUID

The updated contact identifier

Example:
443b03a2-8ec9-b4ba-7315-f0c638748dc3
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "company_name": "Good Burger",
    "title": "Sir",
    "first_name": "Louis",
    "middle_name": "Aloz",
    "last_name": "Kozior",
    "preferred_language_code": "ENG",
    "category_id": "",
    "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
        }
    },
    "company_profile": {
        "industry_id": "4AD9C84FA60F9FE407140E20F707726A",
        "profle_year": 1,
        "annual_turnover": 1,
        "established_on": 1,
        "number_of_employees": 1,
        "registration_number": "",
        "registration_country": "",
        "tax_reference_number": "",
        "vat_registration_number": "",
        "industry_sectors": [
            "4AD9C84FA60F9FE407140E20F707726A"
        ]
    },
    "phones": [
        {
            "id": "",
            "is_primary": true,
            "country_code": "44",
            "number": "238065437",
            "phone_type": "FAX"
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "email_address": "bill@gmail.com",
    "sms_opt_out": true,
    "email_opt_out": true,
    "is_tax_exempt": "false",
    "addresses": [
        {
            "address_type": "ALTERNATIVE",
            "address_name": "My sister's house",
            "is_primary": "true",
            "address_line_1": "",
            "address_line_2": "Thomas V",
            "state_province_county": "Active",
            "town_city": "",
            "postal_code": "",
            "country_code": "CYP",
            "lat": "",
            "lon": "",
            "google_place_id": "",
            "is_billing": true
        }
    ]
}
List Contacts
GET /contacts

Search for Contacts

Request parameters

search_value
string optional

The value of the search across Full Name, Company Name, Contact Code, Phone Number, Email Address, Loyalty Identifier or Serial number of a purchased/rental device (case insensitive)

Example:
C0123456
code
string optional

Unique Code of Contact

Example:
45
first_name
string optional

The first name of contact. Applicable only when searching for physical persons

Example:
John
last_name
string optional

The last name of contact. Applicable only when searching for physical persons

Example:
Doe
company_name
string optional

The name of the company. Applicable only when searching for companies

Example:
CRM
email_address
string optional

The email address of the contact

Example:
info@crm.com
phone_number
string optional

The phone number of the contact

Example:
22265566
statutory_number
string optional

The contact’s unique statutory number

Example:
2342342
include_financials
boolean optional

If set to true then information about the primary account and wallet will be also retrieved

Example:
true
cim
string optional

The customer identification medium

Example:
123456
loyalty_identifier
string optional

The contact’s loyalty identifier

Example:
1234567897415
registered_date
string optional

Filter based on contact registration date

Enumeration:
registered_date[gt]

Returns results where the registration date is greater than this value

registered_date[gte]

Returns results where the registration date is greater than or equal to this value

registered_date[lt]

Returns results where the registration date is less than this value

registered_date[lte]

Returns results where the registration date is less then or equal to this value

owned_by
string GUID optional

The unique identifier of the organisation that owns the contact

Example:
b8821635-09f6-9a97-7ef2-7f5b61c67bcb
metrics
string optional

Defines the additional metrics to be retrieved in the response (comma separated)

Example:
SUBSCRIPTIONS, SCHEMES
country_agreement
string optional

Filters contacts based on the country code that the contact agreed to registered to

Example:
CYP
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
balance_as_of_date
integer optional

If specified, then the balance of the account is as of this date is calculated

tag_ids
array of string optional

filtering by list of tag ids.

Collection format: csv
type
string optional
Enumeration:
PERSON
COMPANY
include_additional_information
boolean optional

Defines whether additional information will be retrieved or not

Example:
true
full_phone_number
string optional

The complete phone number of the contact which includes the country’s dial code

Example:
0035799123456

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The contact code

Example:
ABC-123
contact_type
string

Type of contact support types include Person and Company.

Enumeration:
PERSON
COMPANY
contact_name
string

The contact full name

Example:
John CRM Doe
statutory_number
string

The contact statutory number

Example:
EF00001231
registered_on
integer epoch

The date on which the contact was registered in CRM.COM

category
Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
addresses
Array

Details about contact addresses

Object
id
string GUID

The address identifier

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string

A short name to allow it to be easily recognised in a list

Example:
My house
is_primary
boolean

Defines whether the address is the primary one

Example:
true
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string

The address care of

Example:
n/a
phones
Array

Details about contact’s phone

Object
id
string GUID

The phone identifier

Example:
60bcca96-4965-4d56-8341-cb6f5ae61803
phone_type
string
Enumeration:
LANDLINE
MOBILE
FAX
is_primary
boolean

Defines whether the phone is the primary one

Example:
true
country_code
string

The phone country code

Example:
357
number
string

The phone number

Example:
99999999
email_address
string

The contact’s email

Example:
bill@gmail.com
financials
Object

The primary account of the contact. Available only if “financials” parameter is set to True

account
Object

Account details

id
string GUID

The account identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The account number

Example:
AR123
life_cycle_state
string

The account life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
currency_code
string

The account currency (code)

Example:
EUR
overdue_amount
number

The account overdue amount

Example:
1
balance
number

The account’s running balance as calculated at the time of the Web API call

Example:
200
as_of_date_balance
number

The account’s balance as of a specific date (calculated only if this date is specified in the input parameters)

classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
wallet
Object

Wallet related to the primary account

id
string

Wallet identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

Wallet code

Example:
9000545655567800
life_cycle_state
string

The wallet life cycle state

Enumeration:
EFFECTIVE
TERMINATED
balance
number

Wallet total balance

Example:
9.99
open_balance
number

Wallet’s Open Balance

Example:
4.45
commerce_balance
number

Wallet’s Commerce Balance

Example:
5.54
currency_code
string

Currency code

interaction_status
string enum

The interaction status of the contact, retrieved by REDIS

metrics
Object

Retrieves the metrics requested

subscriptions
Object

Subscription metrics

timestamp
integer epoch

Defaults to current timestamp

Example:
1589791784
total
integer

Total number of Subscriptions

Example:
2
schemes
Object

Reward Schemes metrics

timestamp
integer epoch

Defaults to current timestamp

Example:
1589791784
total
integer

Total number of Schemes

Example:
2
kyc_profile
Object

The contact’s assigned KYC profile

id
string GUID

The KYC Profile identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the KYC profile

Example:
Standard
kyc_status
string

The status of the KYC profile assigned to Contact

Enumeration:
PENDING
VERIFIED
loyalty_identifiers
Array

The contact’s loyalty identifiers (cards)

Object
id
string GUID

The unique identifier of the loyalty identifier (CIM)

Example:
3311eb31-1f2c-5d8f-ae0d-d22595bbfb7a
identifier
string

The loyalty identifier

Example:
234234234324234234234234
country_agreement
string

The country code on which the contact agreed to register to

Example:
CYP
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
additional_information
Object
number_of_subscriptions
integer
number_of_signed_up_reward_schemes
integer
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "code": "ABC-123",
            "contact_type": "PERSON",
            "contact_name": "John CRM Doe",
            "statutory_number": "EF00001231",
            "registered_on": 1,
            "category": {
                "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                "name": "Delivery Purchase"
            },
            "addresses": [
                {
                    "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
                    "address_type": "HOME",
                    "address_name": "My house",
                    "is_primary": true,
                    "address_line_1": "Elia Papakyriakou",
                    "address_line_2": "7 Tower Stars",
                    "state_province_county": "Egkomi",
                    "town_city": "Nicosia",
                    "postal_code": "2015",
                    "country": "CYP",
                    "lat": 35.157115,
                    "lon": 33.313719,
                    "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
                    "care_of": "n/a"
                }
            ],
            "phones": [
                {
                    "id": "60bcca96-4965-4d56-8341-cb6f5ae61803",
                    "phone_type": "LANDLINE",
                    "is_primary": "true",
                    "country_code": "357",
                    "number": "99999999"
                }
            ],
            "email_address": "bill@gmail.com",
            "financials": {
                "account": {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "number": "AR123",
                    "life_cycle_state": "ACTIVE",
                    "currency_code": "EUR",
                    "overdue_amount": 1,
                    "balance": 200,
                    "as_of_date_balance": 1,
                    "classification": {
                        "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                        "name": "Delivery Purchase"
                    }
                },
                "wallet": {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "code": "9000545655567800",
                    "life_cycle_state": "EFFECTIVE",
                    "balance": 9.99,
                    "open_balance": 4.45,
                    "commerce_balance": 5.54,
                    "currency_code": ""
                }
            },
            "interaction_status": "",
            "metrics": {
                "subscriptions": {
                    "timestamp": 1589791784,
                    "total": 2
                },
                "schemes": {
                    "timestamp": 1589791784,
                    "total": 2
                }
            },
            "kyc_profile": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Standard"
            },
            "kyc_status": "PENDING",
            "loyalty_identifiers": [
                {
                    "id": "3311eb31-1f2c-5d8f-ae0d-d22595bbfb7a",
                    "identifier": "234234234324234234234234"
                }
            ],
            "country_agreement": "CYP",
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ],
            "additional_information": {
                "number_of_subscriptions": 1,
                "number_of_signed_up_reward_schemes": 1
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
List Customers
GET /customers

Retrieves the list of contacts (can be filtered based on contact attributes)

Notes

Recommended to be used when creating new Orders, Service Requests, Activities or via external integrations (e.g. POS Integrators)

Request parameters

search_value
string optional

The value of the search across Full Name (Person or Company), Contact Code, Phone Number, Email Address and Loyalty Identifier (case insensitive)

Example:
C0123456
code
string optional

The contact code

Example:
1234
person_name
string optional

The full name of contact. Applicable only when searching for physical persons

Example:
Jack Csak
company_name
string optional

The name of the company. Applicable only when searching for companies

Example:
CRMCY
email_address
string optional

The email address of the contact

Example:
info@crm.com
phone_number
string optional

The phone number of the contact

Example:
22265566
loyalty_identifier
string optional

The contact’s loyalty identifier

Example:
1234567897415
cim
string optional

The customer identification medium

Example:
123456
country_agreement
string optional

Filters contacts based on the country code that the contact agreed to registered to

Example:
CYP
include_financials
boolean optional

If set to true then information about the primary account and wallet will be also retrieved

Example:
true
include_gift_passes
boolean optional

If set to true then any Gift passes redeemed by the customer will also be retrieved

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The contact code

Example:
ABC-123
contact_type
string

Type of contact support types include Person and Company.

Enumeration:
PERSON
COMPANY
contact_name
string

The contact full name (person OR company)

Example:
John CRM Doe
email_address
string

The contact’s email

Example:
info@crm.com
phones
Array

Details about contact’s phone

Object
id
string GUID

The phone identifier

Example:
60bcca96-4965-4d56-8341-cb6f5ae61803
phone_type
string
Enumeration:
LANDLINE
MOBILE
FAX
is_primary
boolean

Defines whether the phone is the primary one

Example:
true
country_code
string

The phone country code

Example:
357
number
string

The phone number

Example:
99999999
loyalty_identifiers
Array

The contact’s loyalty identifiers (cards)

Object
id
string GUID

The unique identifier of the loyalty identifier (CIM)

Example:
3311eb31-1f2c-5d8f-ae0d-d22595bbfb7a
identifier
string

The loyalty identifier

Example:
234234234324234234234234
gift_passes
Array

The contact’s redeemed Gift passes (set as CIM)

Object
code
string

The pass code

Example:
SIOT9W5GGKQQ4
financials
Array

Details about the contact financials. Available only if “include_financials” parameter is set to True

Object
account
Object

Details about the account

id
string GUID

The account identifier

Example:
f77dde12-dcf1-7605-48a4-a10679029b0e
number
string

The account number

Example:
AR1234
currency_code
string

The account currency (code)

Example:
EUR
is_primary
boolean

Defines whether the account is the primary one

Example:
true
life_cycle_state
string

The account life cycle state

Enumeration:
ACTIVE
SUSPENDED
TERMINATED
wallet
Object

The Wallet related to the retrieved Account

id
string

Wallet identifier

Example:
f77dde12-dcf1-7605-48a4-a10679029b0e
code
string

Wallet code

Example:
9000043334321111
life_cycle_state
string

The wallet life cycle state

Enumeration:
EFFECTIVE
TERMINATED
currency_code
string

Currency code

Example:
EUR
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/customers HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "code": "ABC-123",
            "contact_type": "COMPANY",
            "contact_name": "John CRM Doe",
            "email_address": "info@crm.com",
            "phones": [
                {
                    "id": "60bcca96-4965-4d56-8341-cb6f5ae61803",
                    "phone_type": "LANDLINE",
                    "is_primary": "true",
                    "country_code": "357",
                    "number": "99999999"
                }
            ],
            "loyalty_identifiers": [
                {
                    "id": "3311eb31-1f2c-5d8f-ae0d-d22595bbfb7a",
                    "identifier": "234234234324234234234234"
                }
            ],
            "gift_passes": [
                {
                    "code": "SIOT9W5GGKQQ4"
                }
            ],
            "financials": [
                {
                    "account": {
                        "id": "f77dde12-dcf1-7605-48a4-a10679029b0e",
                        "number": "AR1234",
                        "currency_code": "EUR",
                        "is_primary": "true",
                        "life_cycle_state": "ACTIVE"
                    },
                    "wallet": {
                        "id": "f77dde12-dcf1-7605-48a4-a10679029b0e",
                        "code": "9000043334321111",
                        "life_cycle_state": "EFFECTIVE",
                        "currency_code": "EUR"
                    }
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Contact
GET /contacts/{id}

Get details for a specific contact

Path variables

id
string GUID required

The contact (identifier) that should be returned

Example:
ba28b216-d9be-7c12-8305-3427cfa6ed4a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The contact identifier

Example:
ba28b216-d9be-7c12-8305-3427cfa6ed4a
code
string

The contact’s unique code

Example:
ABC-123
contact_type
string

Type of contact support types include Person and Company.

Enumeration:
PERSON
COMPANY
company_name
string

The name of the company if the contact type is COMPANY

Example:
Louis Kozior
title
string

The title of the contact. Applicable only if the type is PERSON

Example:
Sir
first_name
string

The first name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Mark
middle_name
string

The middle name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Jason
last_name
string

The last name of the contact. Applicable and mandatory only if the type is PERSON

Example:
Johnson
contact_name
string

The full name of the Contact taking into consideration the name display settings

Example:
Mark Jason Johnson
preferred_language_code
string

The contact’s preferred language for communication

Example:
ENG
notes
string

Notes for the contact

Example:
Notes
statutory_number
string

The contact’s unique statutory code

Example:
EF-12345
is_tax_exempt
boolean

Defines whether the contact is Tax Exempt or not

Example:
true
category
Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
demographics
Object

Details about the contact’s dmographic information (applicable for PERSON contects)

gender
string

The gender of the contact

Enumeration:
MALE
FEMALE
country_of_residence
string

The contact’s country of residence

passport
Object

Details about the contact’s passport

passport_number
string

The passport number

Example:
PASS1234
issue_country_code
string

The issue country for the passport

Example:
GRC
expiration_date
integer epoch

The expiration date for the passport

Example:
129876567
id_details
Object

Details about the ID (applicable for PERSON contects)

id_number
string

The ID number

Example:
ID1234
issue_country_code
string

The country that issued such ID

Example:
CYP
expiration_date
integer epoch

The expiration date for the ID

Example:
129876567
name_day
Object

Details about the contact nameday (applicable for PERSON contects)

month
integer

The nameday month

Example:
10
day
integer

The nameday day

Example:
4
date_of_birth
Object

Details about the contact birthday (applicable for PERSON contects)

year
integer

The year of birth

Example:
2018
month
integer

The month of birth

Example:
10
day
string

The day of birth

Example:
16
company_profile
Object

A company’s profile. Applicable only if contact_type is COMPANY

industry
Object

The company’s Industry details

id
string
name
string
industry_sectors
Array

The company’s Industry Sectors

Object
id
string
Example:
342343234234
name
string
profile_year
number
Example:
1999
annual_turnover
number
Example:
1
established_on
integer epoch
number_of_employees
number
Example:
1
registration_number
string
registration_country
string
tax_reference_number
string
vat_registration_number
string
phones
Array

Details about the contact’s phones

Object
id
string GUID

The phone identifier

Example:
5203665d-281d-ad97-6643-ae1038d2f6b7
phone_type
string

The phone type

Enumeration:
LANDLINE
MOBILE
FAX
is_primary
boolean

Defines whether the phone number is the primary one

Example:
true
country_code
string

The phone country code (based on ISO 3 char code)

Example:
CYP
number
string

The phone number

Example:
238065437
is_verified
boolean

Defines whether Phone number has been verified

Example:
true
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
email_address
string

The contact’s email

Example:
bill@gmail.com
consent_state
string

The contact’s consent state

Enumeration:
PENDING
REJECTED
ACCEPTED
WITHDRAWN
interaction_status
string enum

The interaction status of the contact, retrieved by REDIS

total_spend
string

The contact’s total spend amount in the last 12 months, retrieved from REDIS

Example:
250
sms_opt_out
boolean
Example:
true
email_opt_out
boolean
Example:
true
referral_code
string

The contact referral code

Example:
REF123
credentials
Array

The contact’s authorisation credentials

Object
name
string

The name of the authorisation credential

Enumeration:
EMAIL
PHONE
FACEBOOK
GOOGLE
value
string

The value of the credential

Example:
johndoe@gmail.com
is_verified
boolean

Defines whether credential has been verified or not

Example:
true
country_agreement
string

The country code on which the contact agreed to register to

Example:
CYP
addresses
Array

Details about the contact’s addresses

Object
id
string GUID

The address identifier

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string

A short name to allow it to be easily recognised in a list

Example:
My house
is_primary
boolean

Defines whether the address is the primary one

Example:
true
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string

The address care of

Example:
n/a
is_anonymised
boolean

Defines whether the contact is anonymized

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/ba28b216-d9be-7c12-8305-3427cfa6ed4a HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ba28b216-d9be-7c12-8305-3427cfa6ed4a",
    "code": "ABC-123",
    "contact_type": "COMPANY",
    "company_name": "Louis Kozior",
    "title": "Sir",
    "first_name": "Mark",
    "middle_name": "Jason",
    "last_name": "Johnson",
    "contact_name": "Mark Jason Johnson",
    "preferred_language_code": "ENG",
    "notes": "Notes",
    "statutory_number": "EF-12345",
    "is_tax_exempt": "true",
    "category": {
        "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
        "name": "Delivery Purchase"
    },
    "demographics": {
        "gender": "MALE",
        "country_of_residence": "",
        "passport": {
            "passport_number": "PASS1234",
            "issue_country_code": "GRC",
            "expiration_date": 129876567
        },
        "id_details": {
            "id_number": "ID1234",
            "issue_country_code": "CYP",
            "expiration_date": 129876567
        },
        "name_day": {
            "month": 10,
            "day": 4
        },
        "date_of_birth": {
            "year": 2018,
            "month": 10,
            "day": "16"
        }
    },
    "company_profile": {
        "industry": {
            "id": "",
            "name": ""
        },
        "industry_sectors": [
            {
                "id": "342343234234",
                "name": ""
            }
        ],
        "profile_year": 1999,
        "annual_turnover": 1,
        "established_on": 1,
        "number_of_employees": 1,
        "registration_number": "",
        "registration_country": "",
        "tax_reference_number": "",
        "vat_registration_number": ""
    },
    "phones": [
        {
            "id": "5203665d-281d-ad97-6643-ae1038d2f6b7",
            "phone_type": "MOBILE",
            "is_primary": true,
            "country_code": "CYP",
            "number": "238065437",
            "is_verified": true
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "email_address": "bill@gmail.com",
    "consent_state": "ACCEPTED",
    "interaction_status": "",
    "total_spend": "250",
    "sms_opt_out": true,
    "email_opt_out": true,
    "referral_code": "REF123",
    "credentials": [
        {
            "name": "EMAIL",
            "value": "johndoe@gmail.com",
            "is_verified": "true"
        }
    ],
    "country_agreement": "CYP",
    "addresses": [
        {
            "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
            "address_type": "ALTERNATIVE",
            "address_name": "My house",
            "is_primary": true,
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2015",
            "country": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
            "care_of": "n/a"
        }
    ],
    "is_anonymised": "false"
}
Delete Contact
DELETE /contacts/{id}

Delete an existing contact

Path variables

id
string GUID required

The contact identifier that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Activity Feed
GET /contacts/{id}/activity_feed
Get Contact Activity Feed
GET /contacts/{id}/activity_feed

Retrieves Contact’s activity feed

Path variables

id
string GUID required

The contact identifier that the activity will be retrieved for

Example:
13cc9948-3560-e10a-e1e4-a73610054933

Request parameters

activity_type
string optional

Filter based on activity type

Enumeration:
INVOICE
PAYMENT
REFUND
CREDIT_NOTE
TOP_UP
TRANSFER
PURCHASE
AWARD
SPEND
ACHIEVEMENT
SERVICE_REQUEST
ACTIVITY
PAYOUT
performed_on
string optional

Filter based on the performed date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. performed_on[gte]=1618395497&performed_on[lt]=1618395497).

Enumeration:
performed_on[gt]

Returns results where the performed date is greater than this value

performed_on[gte]

Returns results where the performed date is greater than or equal to this value

performed_on[lt]

Returns results where the performed date is less than this value

performed_on[lte]

Returns results where the performed date is less then or equal to this value

page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
activity_feed
Array
Object
id
string GUID

The activity unique ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The entity’s number

Example:
I10003
reference_number
string

The entity’s reference number

Example:
Ref12345678
code
string

The entity’s code

Example:
123456789ABE2364
state
string

The entity’s life cycle state

Example:
POSTED
created_date
integer epoch

The date and time where the activity was created

Example:
1576486645
activity_type
string

The activity type

Enumeration:
INVOICE
PAYMENT
REFUND
CREDIT_NOTE
TOP_UP
TRANSFER
PURCHASE
AWARD
SPEND
ACHIEVEMENT
SERVICE_REQUEST
ACTIVITY
PAYOUT
direction
string

The entity’s direction.

Enumeration:
INCOMING
OUTGOING
notes
string

The notes of the activity

Example:
This Invoice is created for November 2019
type
string

The entity’s type name

Example:
INVOICE
total_amount
number

The entity’s total amount

Example:
200
currency
string

The currency code provided in the entity

Example:
EUR
name
string

The activity name

due_date
integer epoch

The entity’s due date in case of Invoices

Example:
1576486645
expiration_date
integer epoch

The entity’s expiration date in case of Awards

Example:
1576486645
reward_offer
string

The name of the reward offer that provided the Award

Example:
Happy Birthday Offer
merchant_name
string

The name of the merchant that the activity was performed for

Example:
Bakery Nicosia
topup_entity
Object

The entity that the topup was performed for

id
string GUID

The unique ID of the topup entity

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The number or code of the topup entity

Example:
AC00123 John Johnson
type
string

The type of the topup entity

Enumeration:
ACCOUNT
WALLET
transfer_origin_entity
Object

The origin entity that the transfer was performed from

id
string GUID

The unique ID of the transfer origin entity

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The number or code of the transfer origin entity

Example:
AC00123 John Johnson
type
string

The type of the transfer origin entity

Enumeration:
ACCOUNT
WALLET
transfer_dest_entity
Object

The destination entity that the transfer was performed for

id
string GUID

The unique ID of the transfer destination entity

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The number or code of the transfer destination entity

Example:
W00123 John Johnson
type
string

The type of the transfer destination entity

Enumeration:
ACCOUNT
WALLET
contact
Object
id
string GUID

Id of Contact receiving transfer of funds

name
string

The full name of the contact that the transfer was sent to

Example:
John Smith
code
string

The unique code of the contact that the transfer was sent to

Example:
89904678
referred_by_account
Object

The referred by account details

id
string GUID

The referred by account identifer

Example:
4bab629d-0d6b-f93b-4664-82cea61c1481
name
string

The referred by account name

Example:
John Doe
number
string

The referred by account number

Example:
AR0000112346
referred_by_contact
Object

The referred by contact details

id
string GUID

The referred by contact identifier

Example:
4bab629d-0d6b-f93b-4664-82cea61c1422
name
string

The referred by contact name

Example:
John Doe
ad_hoc_return
Object

The ad hoc return purchase details

reference_number
string

The ad hoc return purchase reference number

Example:
qwewe234-dfsf234324-dwrwerw
ad_hoc_return_date
integer epoch

The date that the ad hoc return purchase is requested

Example:
1601636257
amount
number

The amoount that the customer was debitied due to ad hoc return

Example:
299.99
currency
string

The currency code of the ad hoc return request

Example:
EUR
request_amount
number

The ad hoc return request amount

Example:
999.99
payment
Array

Payment method(s)

Object
id
string

payment method id

method
string

Payment method

Example:
CARD
identifier
string

An identifier that briefly describes the contact’s payment method (The last 4 digits for cards, the email for Paypal accounts or the wallet number

Example:
**** 1234
allocations
Array

How an entity is allocated (e.g. a credit note)

Object
id
string GUID

The financial transaction type unique identifier

name
string

The financial transaction type name

Example:
Purchase
purchase_discount
number

Purchase discount amount

Example:
2.4
financials
string
owner
Object
id
string
Example:
&686786876HGHJDG
name
string
Example:
John Doe
priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW
date
string

scheduled date

from_time
string
to_time
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/13cc9948-3560-e10a-e1e4-a73610054933/activity_feed HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "activity_feed": [ 
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "number": "I10003",
            "reference_number": "Ref12345678",
            "code": "123456789ABE2364",
            "state": "POSTED",
            "created_date": 1576486645,
            "activity_type": "ACTIVITY",
            "direction": "OUTGOING",
            "notes": "This Invoice is created for November 2019",
            "type": "INVOICE",
            "total_amount": 200,
            "currency": "EUR",
            "name": "",
            "due_date": 1576486645,
            "expiration_date": 1576486645,
            "reward_offer": "Happy Birthday Offer",
            "merchant_name": "Bakery Nicosia",
            "topup_entity": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "number": "AC00123 John Johnson",
                "type": "WALLET"
            },
            "transfer_origin_entity": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "number": "AC00123 John Johnson",
                "type": "ACCOUNT"
            },
            "transfer_dest_entity": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "number": "W00123 John Johnson",
                "type": "ACCOUNT",
                "contact": {
                    "id": "",
                    "name": "John Smith",
                    "code": "89904678"
                }
            },
            "referred_by_account": {
                "id": "4bab629d-0d6b-f93b-4664-82cea61c1481",
                "name": "John Doe",
                "number": "AR0000112346"
            },
            "referred_by_contact": {
                "id": "4bab629d-0d6b-f93b-4664-82cea61c1422",
                "name": "John Doe"
            },
            "ad_hoc_return": {
                "reference_number": "qwewe234-dfsf234324-dwrwerw",
                "ad_hoc_return_date": 1601636257,
                "amount": 299.99,
                "currency": "EUR",
                "request_amount": 999.99
            },
            "payment": [
                {
                    "id": "",
                    "method": "CARD",
                    "identifier": "**** 1234"
                }
            ],
            "allocations": [
                {
                    "id": "",
                    "name": "Purchase"
                }
            ],
            "purchase_discount": 2.4,
            "financials": "",
            "owner": {
                "id": "&686786876HGHJDG",
                "name": "John Doe"
            },
            "priority": "LOW",
            "date": "",
            "from_time": "",
            "to_time": ""
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Address
POST /contacts/{id}/addresses
PUT /contacts/{id}/addresses/{address_id}
DELETE /contacts/{id}/addresses/{address_id}
GET /contacts/{id}/addresses/
Add Contact Address
POST /contacts/{id}/addresses

Add a new address to an existing contact. A contact can have multiple addresses

Path variables

id
string GUID required

The contact identifier that the address should be added

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object

Information about an address of the contact

address_type
string required

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string nullable

A short name to allow it to be easily recognised in a list

Example:
My sister's house
is_primary
boolean nullable

Defines whether the address is the primary one (used for billing or communication purposes)

Default:
false
Example:
true
address_line_1
string required

The address line 1 (main address information

Example:
Elia Papakyriakou
address_line_2
string nullable

The address line 2 (additional information)

Example:
7 Tower Stars
state_province_county
string nullable

The address state/province/county

Example:
Egkomi
town_city
string nullable

The address town/city

Example:
Nicosia
postal_code
string nullable

The address postal code

Example:
2000
country_code
string required

The address country code (3 char code based)

Example:
CYP
lat
number nullable

The latitude of the address

Example:
35.157115
lon
number nullable

The longitude of the address

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string nullable

The address care of

Example:
n/a

Responses

200 200

Successful Request

Body
Object
id
string GUID

The address identifier

Example:
9d1df8ce-cecd-d335-2b44-2644c9576e6f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses HTTP/1.1 

Content-Type: application/json

{
    "address_type": "HOME",
    "care_of": "",
    "is_primary": true,
    "address_line_1": "",
    "address_line_2": "Thomas V",
    "state_province_county": "Active",
    "town_city": "",
    "postal_code": "",
    "country_code": "CYP"
}
Update Contact Address
PUT /contacts/{id}/addresses/{address_id}

Update an existing address of a contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_id
string GUID required

The address identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object

Information about an address of the contact

address_type
string required

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string nullable

A short name to allow it to be easily recognised in a list

Example:
My sister's house
is_primary
boolean nullable

Defines whether the address is the primary one (used for billing or communication purposes)

Default:
false
Example:
true
address_line_1
string required

The address line 1 (main address information

Example:
Elia Papakyriakou
address_line_2
string nullable

The address line 2 (additional information)

Example:
7 Tower Stars
state_province_county
string nullable

The address state/province/county

Example:
Egkomi
town_city
string nullable

The address town/city

Example:
Nicosia
postal_code
string nullable

The address postal code

Example:
2000
country_code
string required

The address country code (3 char code based)

Example:
CYP
lat
number nullable

The latitude of the address

Example:
35.157115
lon
number nullable

The longitude of the address

Example:
33.313719
google_place_id
string nullable

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string nullable

The address care of

Example:
n/a

Responses

200 200

Successful Request

Body
Object
id
string GUID

The address identifier

Example:
9d1df8ce-cecd-d335-2b44-2644c9576e6f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "type": "HOME",
    "address_name": "",
    "care_of": "",
    "is_primary": true,
    "address_line_1": "",
    "address_line_2": "Thomas V",
    "state_province_county": "Active",
    "town_city": "",
    "postal_code": "",
    "country_code": "CYP",
    "lat": 35.157115,
    "lon": 33.313719,
    "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
}
Remove Contact Address
DELETE /contacts/{id}/addresses/{address_id}

Removes a contact address. A single address can be removed at a time

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
address_id
string GUID required

The contact identifier that will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/addresses/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Contact Addresses
GET /contacts/{id}/addresses/

Lists the addresses associated to the contact.

Path variables

id
string required

id of contact

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
search_value
string optional

Value to search by name etc.

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The address identifier

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string

A short name to allow it to be easily recognised in a list

Example:
My house
is_primary
boolean

Defines whether the address is the primary one

Example:
true
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string

The address care of

Example:
n/a
Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/{id}/addresses/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
            "address_name": "My house",
            "address_type": "HOME",
            "is_primary": true,
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2015",
            "country": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    ]
}
Attachments
POST /contacts/{id}/files
DELETE /contacts/{id}/files/{file_id}
GET /contacts/{id}/files
Add Contact Attachment
POST /contacts/{id}/files

Connect an uploaded file to an existing contact

Path variables

id
string GUID required

The contact (identifier) that file will be attached

Example:
66451204-4404-894c-4dc6-486c540ece40

Notes

FILE UPLOAD FLOW

Integrating file upload for Contacts should be based on the following APIs

  1. Upload File Signature
  2. Add Contact Attachment

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required nullable

The file (identifier) to be attached

Example:
30526723-24a3-e4e3-1a75-b26b1b41f05c
url
string required nullable

URL of the file to be attached

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
description
string nullable

The file description

Example:
Screenshot sent by customer

Responses

200 OK
Body
Object
id
string GUID

The service request identifier

Example:
66451204-4404-894c-4dc6-486c540ece40
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

Content-Type: application/json

{
    "file_id": "30526723-24a3-e4e3-1a75-b26b1b41f05c",
    "url": "https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug",
    "description": "Screenshot sent by customer"
}
Delete Contact Attachment
DELETE /contacts/{id}/files/{file_id}

Delete a specific contact attachment file

Path variables

id
string GUID required

The contact (identifier) that file will be deleted

Example:
66451204-4404-894c-4dc6-486c540ece40
file_id
string GUID required

The attachment file (identifier) that will be deleted

Example:
04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/66451204-4404-894c-4dc6-486c540ece40/files/04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Contact Attachments
GET /contacts/{id}/files

Retrieve all attachment files for a specific contact

Path variables

id
string GUID required

The contact (identifier) that files will be retrieved

Example:
66451204-4404-894c-4dc6-486c540ece40

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The attachment identifier

Example:
3ae9d64a-8a3b-f1e1-eed6-05b307f926fb
mime
string

The mime type of the uploaded file

Enumeration:
csv
doc
docx
xls
xlsx
pdf
log
txt
png
jpg
jpeg
svg
description
string

The attachement description

Example:
Screenshot sent by customer
file
Object

The attachement file details

id
string GUID

The file identifier

Example:
0317868f-28f8-9f56-d248-5a78718b38cc
url
string

The file URL endpoint

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
name
string

The file name

Example:
img.png
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
            "mime": "png",
            "description": "this is a brief description of this image",
            "file": {
                "id": "0317868f-28f8-9f56-d248-5a78718b38cc",
                "name": "img.png"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Cards
POST /contacts/{id}/cards
Add Card (Roadmap)
POST /contacts/{id}/cards

Add a card on a contact (card will be hashed and added as a cim)

Path variables

id
string GUID required

The contact (identifier) on which a card will be added

Example:
3904d9c5-0356-f1c8-9622-b8b39287e251

Notes

CRM Card Services

PAN Based

A card will be hashed only based on the provided 16digit PAN number.

Card Details Based

A card will be hashed based on the provided last 4 digit, expiration month/year and card owner surname.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
pan_number
string required nullable

The card pan number

Example:
4242424242424242
last4
string required nullable

The card last 4 digits

Example:
4242
expiration_month
integer required nullable

The card expiration month

Example:
12
expiration_year
integer required nullable

The card expiration year

Example:
24
card_owner
Object required nullable

Details about the card owner

surname
string required nullable

The card owner surname

Example:
doe
gateway_token
Array required

Information regarding the card tokenization via a payment gateway

Object
integration_id
string GUID required

The integration (identifier) which is used in the front end

Example:
d693bbcc-d38c-5463-88fd-2e0279150070

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
POST https://sandbox.crm.com/backoffice/v1/contacts/3904d9c5-0356-f1c8-9622-b8b39287e251/cards HTTP/1.1 

Content-Type: application/json

{
    "pan_number": "4242424242424242",
    "gateway_token": [
        {
            "integration_id": "d693bbcc-d38c-5463-88fd-2e0279150070"
        }
    ]
}

HTTP/1.1 200 OK 
POST https://sandbox.crm.com/backoffice/v1/contacts/3904d9c5-0356-f1c8-9622-b8b39287e251/cards HTTP/1.1 

Content-Type: application/json

{
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 24,
    "card_owner": {
        "surname": "doe"
    },
    "gateway_token": [
        {
            "integration_id": "d693bbcc-d38c-5463-88fd-2e0279150070"
        }
    ]
}

HTTP/1.1 200 OK 
PUT /contacts/{id}/consents
POST /contacts/{id}/anonymize
PUT /contacts/{id}/consents

Updates the Consent state of the Contact

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
consent_state
string required

The contact’s consent state

Enumeration:
PENDING
REJECTED
ACCEPTED
WITHDRAWN

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the contact

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/consents HTTP/1.1 

Content-Type: application/json

{
    "consent_state": "REJECTED"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Anonymize Contact
POST /contacts/{id}/anonymize

Contact Anonymisation is the process of encrypting or removing personally identifiable data from data sets so that the person can no longer be identified directly or indirectly.

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string

The contact unique identifier to whom the user will transfer the wallet money

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/anonymize HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Loyalty Identifier
POST /contacts/{id}/loyalty_identifiers
DELETE /contacts/{id}/loyalty_identifiers/{loyalty_id}
GET /contacts/{id}/loyalty_identifiers
Add Loyalty Identifier
POST /contacts/{id}/loyalty_identifiers

Add a new loyalty identifier to an existing contact. A contact can have multiple loyalty identifiers

Path variables

id
string GUID required

The contact (identifier) whose loyalty identifier will be created

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
identifier
string required

The loyalty identifier

Example:
123234345624356213

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the loyalty identifier (CIM)

Example:
891d84dd-4b3b-84b3-ba87-aa63fed3b88a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/loyalty_identifiers HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "identifier": "123234345624356213"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "891d84dd-4b3b-84b3-ba87-aa63fed3b88a"
}
Remove Loyalty Identifier
DELETE /contacts/{id}/loyalty_identifiers/{loyalty_id}

Removes a contact loyalty identifier. A single loyalty identifier can be removed at a time

Path variables

id
string GUID required

The contact (identifier) whose phone will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
loyalty_id
string GUID required

The loylaty (identifier) (CIM based) that will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/loyalty_identifiers/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Loyalty Identifiers
GET /contacts/{id}/loyalty_identifiers

Retrieve the loyalty identifiers for a specific contact

Path variables

id
string GUID required

The contact (identifier) wholse loyalty identiers will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The unique identifier of the loyalty identifier (CIM)

Example:
1adaae9e-6dbb-f389-e5d0-8288f0c87a62
identifier
string

The loyalty identifier

Example:
2143454566754
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/loyalty_identifiers HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "1adaae9e-6dbb-f389-e5d0-8288f0c87a62",
            "identifier": "2143454566754"
        }
    ]
}
Communities
POST /contacts/{id}/relationships
PUT /contacts/{id}/relationships
DELETE /contacts/{id}/relationships/{child_id}
GET /contacts/{id}/relationships/
Create Contact Relationship
POST /contacts/{id}/relationships

This process creates a relationship between a parent contact and a child contact

Path variables

id
string required

the GUID of the parent ie.business or main member

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
contact_id
string
Example:
JKHDSJKHDSKJHDKJHS
relationship
string
Example:
Employee
role
string
Example:
Manager
first_name
string
Example:
John
last_name
string
Example:
Doe
email
string
Example:
johndoe@crm.com
phone
Object
country_code
string
Example:
CYP
number
string
Example:
22265566
Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/{id}/relationships HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "contact_id": "JKHDSJKHDSKJHDKJHS",
    "role": "HR Manager",
    "relationship": "FAMILY",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@yahoo.com",
    "phone": {
        "country_code": "+27",
        "number": "744444121"
    }
}
Update Contact Relationship
PUT /contacts/{id}/relationships

This process creates a relationship between a parent contact and a child contact.

Path variables

id
string GUID required

The GUID of the parent ie.business or main member

Example:
719ee10e-a6c3-68b3-d5bf-30473eacd927

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID

id of child contact

Example:
20f744b5-6c18-39b3-e770-9d228f60b21f
role
string

Role of contact

Example:
HR Manager
relationship
string

The relationship of contact

Enumeration:
FAMILY
FRIENDS
EMPLOYEE
Example 1
PUT https://sandbox.crm.com/backoffice/v1/contacts/{id}/relationships HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "id": "JKSDKJHDSKJH",
    "role": "HR Manager",
    "relationship": "FAMILY"
}
Delete Contact Relationship
DELETE /contacts/{id}/relationships/{child_id}

The following process deletes the relationship between a two contacts.

Path variables

id
string GUID required

The parent contact (identifier)

Example:
JHDKJHADKJHSDKJH
child_id
string GUID required

The child contact (identifier)

Example:
JGDSKJGHDKJH
Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/JHDKJHADKJHSDKJH/relationships/JGDSKJGHDKJH HTTP/1.1 
List Contact Relationships
GET /contacts/{id}/relationships/

Lists all the relationships for the contact. Also retrieves the deatils of the contact ie. name and role for the contact relationship.

Path variables

id
string GUID required

The contact identifier whose relationships will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
contact_type
string optional

This field will determine whether to show the PARENT or the CHILD information.

Enumeration:
PARENT
CHILD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string

The id of the relationship.

Example:
JHDKJHDKAJHD
role
string

The role specified of the child contact.

Example:
HR Manager
relationship
string

The relationship of contact

Enumeration:
FAMILY
FRIENDS
EMPLOYEE
contact
Object

Details relating to the contact.

id
string

The id of the child contact

Example:
KJDKJHADKH
first_name
string

The first name of the child contact

Example:
John Smith
last_name
string
email
string

Email relating to the contact

Example:
john.smith@gmail.com
phone
Object
country_code
string
number
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/relationships/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JHDKJHDKAJHD",
            "role": "HR Manager",
            "relationship": "EMPLOYEE",
            "contact": {
                "id": "KJDKJHADKH",
                "name": "John Smith",
                "email": "john.smith@gmail.com",
                "phone": {
                    "country_code": "",
                    "number": ""
                }
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Tags

The following process relates to tag functionality for contacts

POST /contacts/{id}/tags
PUT /contacts/{id}/tags
DELETE /contacts/{id}/tags/{tag_id}
GET /contacts/{id}/tags
Add tags to contact
POST /contacts/{id}/tags

The following process adds tags to a contact

Path variables

id
string required

The contact GUID

Example:
HRDGSWRSFVSDSDBSDSSDDE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string GUID

The tag id

Example:
FDHNFDBR675765ghdh
Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/HRDGSWRSFVSDSDBSDSSDDE/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "FDHNFDBR675765ghdh"
        }
    ]
}
Update tags for contact
PUT /contacts/{id}/tags

The following process updates tags for a contact

Path variables

id
string required

The contact GUID

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
JGFJHGJHSDGHJSG
Example 1
PUT https://sandbox.crm.com/backoffice/v1/contacts/{id}/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "JGFJHGJHSDGHJSG"
        }
    ]
}
Delete Tag for Contact
DELETE /contacts/{id}/tags/{tag_id}

Deletes a tag on a contact.

Path variables

id
string GUID required

The id of the contact.

Example:
JFGJKSFGJFSGH
tag_id
string GUID required

The id of the tag

Example:
KJDFHKJGFSJHG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/JFGJKSFGJFSGH/tags/KJDFHKJGFSJHG HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Get tags for contact
GET /contacts/{id}/tags

The following process retrieves the tags for a contact

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

the tag ID

Example:
JKGJHFSDJHGDSJHGA
name
string

Name of Tag

Example:
Maintenance
colour
string

Colour of tag

Example:
The colour of the tag
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/{id}/tags HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JKGJHFSDJHGDSJHGA",
            "name": "Maintenance",
            "colour": "The colour of the tag"
        }
    ]
}
KYC Profile
PUT /contacts/{id}/kyc_profile
POST /contacts/{id}/kyc_profile
Update Contact KYC Profile - NOT USED
PUT /contacts/{id}/kyc_profile

Update the contact’s KYC profile

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
kyc_id
string GUID

The id of the KYC to be provided to the contact

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the contact

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/kyc HTTP/1.1 

Content-Type: application/json

{
    "kyc_id": "4AD9C84FA60F9FE407140E20F707726A"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Verify Contact KYC Profile
POST /contacts/{id}/kyc_profile

Set the KYC profile status of a Contact as Verified

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/kyc/verify HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Organisation Operations
POST /contacts/{id}/organisations
Sign up/out Organisation
POST /contacts/{id}/organisations

Contact joins an existing organisation

Path variables

id
string GUID required

The contact (registry) (identifier) that will sign up/out to/from an organisation

Example:
0b2c2111-0294-59f1-8a39-92039444a2f6

Notes

CONTACT REGISTRY

Contacts should belong to the service owner registry and via API integration a user can sign up/off such contacts to/from a business that utilise such service owner contact registry

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The action that should be applied on the organisation

Enumeration:
SIGNUP
SIGNOFF
organisation_id
string GUID

The organisation identifier that the action will be applied

Example:
db50a590-7de3-3b2d-33a6-91a25e83d3e6
service_acceptance
string nullable

Defines whether the contact has accepted the client service (applicable only if action = SIGNUP)

Default:
true
Example:
true
email_opt_out
string nullable

The contact setting for receiving emails (applicable only if action = SIGNUP)

Default:
false
Example:
true
sms_opt_out
string nullable

The contact setting for receiving sms (applicable only if action = SIGNUP)

Default:
false
Example:
true
consent_state
string nullable

The contact setting for consent (applicable only if action = SIGNUP)

Enumeration:
ACCEPTED
PENDING
REJECTED
WITHDRAWN

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
POST https://sandbox.crm.com/backoffice/v1/contacts/0b2c2111-0294-59f1-8a39-92039444a2f6/organisations HTTP/1.1 

Content-Type: application/json

{
    "action": "SIGNUP",
    "organisation_id": "db50a590-7de3-3b2d-33a6-91a25e83d3e6",
    "service_acceptance": "true",
    "email_opt_out": "false",
    "sms_opt_out": "false",
    "consent_state": "ACCEPTED",
    "referral_code": "1234"
}

HTTP/1.1 200 OK 
POST https://sandbox.crm.com/backoffice/v1/contacts/0b2c2111-0294-59f1-8a39-92039444a2f6/organisations HTTP/1.1 

Content-Type: application/json

{
    "action": "SIGNOFF",
    "organisation_id": "db50a590-7de3-3b2d-33a6-91a25e83d3e6"
}

HTTP/1.1 200 OK 
Password
POST /contacts/{id}/otp
GET /contacts/{id}/validate-otp
POST /contacts/change_password
Request One Time Password
POST /contacts/{id}/otp

Request a one-time-password for a specific contact. The request sends an outbound validation number that can be used to verify the contact.

Path variables

id
string GUID required

The contact (identifier) that a one-time-password will be created for

Example:
33749faa-4ef0-426d-f9f0-83b91bf5ab3f

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
send_method
string
Enumeration:
EMAIL

Send otp to contact’s email address

SMS

Send otp to contact’s primary phone number

Responses

200 OK

Request Successfull

Body
Object
obfuscated_value
string

The obfuscated value of the email or sms used to send the otp

Example:
+35799***834
auth_otp
string

The one time password auth id

Example:
731e4023-4c04-4278-8eb5-240651317e46
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/33749faa-4ef0-426d-f9f0-83b91bf5ab3f/tokens HTTP/1.1 

Content-Type: application/json

{
    "intent": "SPEND",
    "spend_amount": 14.52
}

HTTP/1.1 200 OK 
Validate One Time Password
GET /contacts/{id}/validate-otp

Verifies an one time password that was sent to contact

Path variables

id
string required

The contact (identifier) for which the one-time-password will be validated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
auth_otp
string

One Time Password Auth Id

Example:
81b4361b-5d1d-1530-47c7-318202dbe45d
code
string

The OTP that should be used for verification purposes

Example:
654321

Responses

200 OK

The request has succeeded

Body
Object
id
string

The contact identifier

Example:
330ab797-7e42-f509-9c45-dec5be70c706
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Change Password
POST /contacts/change_password

Changes the password for a contact’s identity

Request body

Object
token
string required nullable

The token that will verify that the client is trusted (required only if the identity is EMAIL based)

Example:
ABCTKN123456798VGP2020
password
string required

The new password

Example:
wsxcde421qadfg

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/contacts/change_password HTTP/1.1 

Content-Type: application/json

{
    "token": "ABCTKN123456798VGP2020",
    "password": "wsxcde421qadfg"
}

HTTP/1.1 200 OK 
Payment Methods

Allow for management of payment methods for contacts.

POST /contacts/{id}/payment_methods
PUT /contacts/{id}/payment_methods/{payment_method_id}
DELETE /contacts/{id}/payment_methods/{payment_method_id}
GET /contacts/{id}/payment_methods
Add Payment Method
POST /contacts/{id}/payment_methods

Add a new payment method for a contact. The payment method’s details will be passed over to a Payment Gateway Integrator

Path variables

id
string required

The contact’s unique identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the payment method

payment_method_type
string

Only Account Debits are allowed to be added as payment methods in the back-end

Enumeration:
ACCOUNT_DEBIT
CARD
WALLET
is_primary
boolean

If the new payment method is the first one for the contact, then it will be automatically set as the primary one. If another primary method exists, then this new payment method becomes the new primary.

is_backup
boolean

If another backup method exists, then this new payment method becomes the new backup

notes
string
account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string nullable

The bank account number.

Example:
001002001
iban
string required nullable

The IBAN code.

Example:
0143240434320434
bank
string nullable

The name of the customer’s bank

Example:
Barclays
bank_code
string nullable

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string nullable

The bank account swift number

Example:
12345678
sort_code
string nullable

The sort code

Example:
20-02-53
mandate
Object
reference
string
type
string

The mandate (sequence) type

Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
sign_date
integer epoch
Example:
1654756878
termination_date
integer epoch
Example:
1654756887
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
integration_id
string

The payment gateway’s integration identifier

account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_state
string
address_city
string
address_zip
string
address_coutry
string
use_billing_address
boolean
country
string

The country the bank account is located in.

Example:
CY
currency
string
Example:
EUR
card
Object

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
Default Card
brand
string

The card’s brand

Example:
VISA
first6
string

The card’s first 6 digits

Example:
424242
last4
string

The card’s lat 4 digits

Example:
4242
expiration_month
integer

The card’s expiration month

Example:
1
expiration_year
integer

The card’s expiration year

Example:
2020
country_of_issue
string

The card’s coutry of issue (3 code based)

Example:
CYP
card_holder_details
Object

Details about the cardholder owner

card_holder_name
string

The name of the card holder

Example:
John Doe
address_line_1
string

The address related to the card

Example:
Elia Papakyriakou
address_line_2
string

Additional address information related to the card

Example:
7 Tower Star
address_city
string

The city related to the card

Example:
Nicosia
address_zip
string

The zip code related to the card

Example:
2415
address_state
string

The state related to the card

Example:
Nicosia
address_country
string

The country related to the card

Example:
CYP
gateway_token
Array

Details about the gateway that a card related token was issued

Object
gateway
string nullable

Defines the gateway that issued such token

Enumeration:
JCC
SETTLE
integration_id
string GUID nullable

The gateway integration (identifier)

Example:
bce504a4-f712-5262-183c-f58218a7a0ed
token
string required

The card related token

Example:
Xt5EWLLDS7FJjR1c

Responses

201 Created
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/{id}/payment_methods HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "type": "CARD",
    "is_primary": true,
    "is_backup": true,
    "notes": "",
    "account_debit": {
        "account_name": "",
        "account_number": "001002001",
        "iban": "0143240434320434", 
        "bank": "Barclays",
        "bank_code": "0032933-1123",
        "branch": "Ascot",
        "swift": "12345678",
        "sort_code": "20-02-53",
        "mandate": {
            "reference": "",
            "sign_date": 1
        },
        "account_type": "SAVINGS",
        "integration_id": "",
        "account_holder_details": {
            "account_holder_name": "",
            "address_line_1": "",
            "address_line_2": "",
            "address_state": "",
            "address_city": "",
            "address_zip": "",
            "address_coutry": "",
            "use_billing_address": true
        },
        "country": "CY",
        "currency": "EUR"
    },
    "card": {
        "name": "Default Card",
        "brand": "VISA",
        "first6": "424242",
        "last4": "4242",
        "expiration_month": 1,
        "expiration_year": 2020,
        "country_of_issue": "CYP",
        "card_holder_details": {
            "card_holder_name": "John Doe",
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Star",
            "address_city": "Nicosia",
            "address_zip": "2415",
            "address_state": "Nicosia",
            "address_country": "CYP"
        },
        "gateway_token": [
            {
                "gateway": "SETTLE",
                "integration_id": "bce504a4-f712-5262-183c-f58218a7a0ed",
                "token": "Xt5EWLLDS7FJjR1c"
            }
        ]
    }
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": ""
}
Update Payment Method
PUT /contacts/{id}/payment_methods/{payment_method_id}

Update a payment method for a contact

Path variables

id
string required

The contact identifier for which a payment method will be added

payment_method_id
string required

The payment method id that will be updated

Notes

JCC Merchant Gateway

  • Perform Fingerprint to retrieve the card masked & hashed numbers and the country of issue
  • Set the retrieved masked number, hashed number and country of issue on the related “card” collection

Settle Gateway

  • Set the phone country code, phone number and msisdn (phone country + number) on the related “phone” collection

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
is_primary
boolean

Marks the payment method as the contact’s primary one

is_backup
boolean

Marks the payment method as the backup

notes
string

Notes related to te payment method

account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string nullable

The bank account number.

Example:
001002001
iban
string required nullable

The IBAN code.

Example:
0143240434320434
bank
string nullable

The name of the customer’s bank

Example:
Barclays
bank_code
string nullable

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string nullable

The bank account swift number

Example:
12345678
sort_code
string nullable

The sort code

Example:
20-02-53
country
string

The country the bank account is located in.

Example:
CY
mandate
Object
reference
string
type
string

The mandate (sequence) type

Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
sign_date
integer
termination_date
integer
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
currency
string
Example:
EUR
account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_state
string
address_city
string
address_zip
string
address_coutry
string
use_billing_address
boolean
card
Object

Applicable only when updating a payment method of type Card

exp_month
string
Example:
12
exp_year
string
Example:
25

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated payment method

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/contacts/{id}/payment_methods/{payment_method_id} HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "is_primary": true,
    "is_backup": true,
    "notes": "",
    "account_debit": {
        "account_name": "",
        "account_number": "001002001",
        "iban": "0143240434320434",
        "bank": "Barclays",
        "bank_code": "0032933-1123",
        "branch": "Ascot",
        "swift": "12345678",
        "sort_code": "20-02-53",
        "country": "CY",
        "mandate": {
            "reference": "",
            "sign_date": 1
        },
        "currency": "EUR",
        "account_type": "SAVINGS",
        "account_holder_details": {
            "account_holder_name": "",
            "address_line_1": "",
            "address_line_2": "",
            "address_state": "",
            "address_city": "",
            "address_zip": "",
            "address_coutry": "",
            "use_billing_address": true
        }
    },
    "card": {
        "exp_month": "12",
        "exp_year": "25"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
}
Delete Payment Method
DELETE /contacts/{id}/payment_methods/{payment_method_id}

Deletes a payment method for a contact

Path variables

id
string required

The id of the contact

Example:
JGKDJHAK76786JUGJHDG
payment_method_id
string required

The id of the payment method.

Example:
SHDGJKSHDJKHS86876HGFHDGSFHSF

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/JGKDJHAK76786JUGJHDG/payment_methods/SHDGJKSHDJKHS86876HGFHDGSFHSF HTTP/1.1 
List Payment Methods
GET /contacts/{id}/payment_methods

List of Payment methods allocated to contact

Path variables

id
string GUID required

The contact identifier whose payment methods will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
type
string optional

Filters the contact’s payment methods based on type

Enumeration:
CARD

Credit/Debit/Prepaid cards

WALLET

Wallet related to either a card, bank account or has a monetary value

ACCOUNT_DEBIT

Collect money directly from an account

Example:
CARD
is_primary
boolean optional
is_backup
boolean optional

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The payment method identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string
is_primary
boolean

Indicates which payment mehod is the contact’s primary one

Example:
true
is_backup
boolean

Indicates which payment mehod is the contact’s backup one

Example:
true
payment_method_type
string

The type of the event

Enumeration:
CARD

Credit/Debit/Prepaid cards

WALLET

Wallet related to either a card, bank account or has a monetary value

ACCOUNT_DEBIT

Collect money directly from an account

Example:
CARD
card
Object

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
Default Card
brand
string

The card’s brand

Example:
VISA
funding_type
string

The type of the event

Enumeration:
CREDIT
DEBIT
PREPAID
Example:
CREDIT
first6
string

The first 6 digits of the card. Either the card number or the first 6 and last 4 digits must be specified

last4
string

The last 4 digits f the card. Either the card number or the first 6 and last 4 digits must be specified

expiration_month
integer

The card expiration month

Example:
1
expiration_year
integer

The card expiration year

Example:
2020
country_of_issue
string

The card issue country (3 char country code)

Example:
CYP
cvc
string
card_holder_details
Object

Information about the card holder

card_holder_name
string

The name of the card holder

Example:
John Doe
address_line_1
string

The address related to the card

Example:
Elia Papakyriakou
address_line_2
string

Additional address information related to the card

Example:
7 Tower Star
address_city
string

The city related to the card

Example:
Nicosia
address_zip
string

The zip code related to the card

Example:
2415
address_state
string

The state related to the card

Example:
Nicosia
address_country
string

The country related to the card

Example:
CYP
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string

The bank account number.

Example:
001002001
iban
string

The IBAN code.

Example:
0143240434320434
bank
string

The name of the customer’s bank

Example:
Barclays
bank_code
string

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string

The identifier of the bank branch

Example:
Ascot
swift
string

The bank account swift number

Example:
12345678
sort_code
string

The sort code

Example:
20-02-53
country
string

The country the bank account is located in.

Example:
CY
currency
string
Example:
EUR
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
mandate
Object
reference
string
sign_date
integer
termination_date
integer
type
string
Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_city
string
address_state
string
address_zip
string
address_country
string
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
wallet
Object

The card’s main information. Required and applicable if the payment method type is CARD

email
string nullable

The email used when registering to the walled-based payment method

Example:
jsmith@email.com
phone
Object nullable

The phone used when registering to the walled-based payment method

name
string
country_code
string
number
string
msisdn
string
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/payment_methods HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "",
            "is_primary": true,
            "is_backup": true,
            "payment_method_type": "CARD",
            "card": {
                "name": "Default Card",
                "brand": "VISA",
                "funding_type": "CREDIT",
                "first6": "",
                "last4": "",
                "expiration_month": 1,
                "expiration_year": 2020,
                "country_of_issue": "CYP",
                "cvc": "",
                "card_holder_details": {
                    "card_holder_name": "John Doe",
                    "address_line_1": "Elia Papakyriakou",
                    "address_line_2": "7 Tower Star",
                    "address_city": "Nicosia",
                    "address_zip": "2415",
                    "address_state": "Nicosia",
                    "address_country": "CYP"
                },
                "gateway_token": [
                    {
                        "token": "",
                        "gateway": "SETTLE",
                        "integration": {
                            "id": "",
                            "name": ""
                        }
                    }
                ]
            },
            "account_debit": {
                "account_name": "",
                "account_number": "001002001",
                "iban": "0143240434320434",
                "bank": "Barclays",
                "bank_code": "0032933-1123",
                "branch": "Ascot",
                "swift": "12345678",
                "sort_code": "20-02-53",
                "country": "CY",
                "currency": "EUR",
                "account_type": "SAVINGS",
                "mandate": {
                    "reference": "",
                    "sign_date": 1,
                    "termination_date": 1,
                    "type": "ONEOFF"
                },
                "account_holder_details": {
                    "account_holder_name": "",
                    "address_line_1": "",
                    "address_line_2": "",
                    "address_city": "",
                    "address_state": "",
                    "address_zip": "",
                    "address_country": ""
                },
                "gateway_token": [
                    {
                        "token": "",
                        "gateway": "JCC_MERCHANT",
                        "integration": {
                            "id": "",
                            "name": ""
                        }
                    }
                ]
            },
            "wallet": {
                "email": "jsmith@email.com",
                "phone": {
                    "name": "",
                    "country_code": "",
                    "number": "",
                    "msisdn": ""
                },
                "gateway_token": [
                    {
                        "token": "",
                        "gateway": "SETTLE",
                        "integration": {
                            "id": "",
                            "name": ""
                        }
                    }
                ]
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Phone
POST /contacts/{id}/phones
PUT /contacts/{id}/phones/{phone_id}
DELETE /contacts/{id}/phones/{phone_id}
Add Contact Phone
POST /contacts/{id}/phones

Add a new phone to an existing contact. A contact can have multiple phones

Path variables

id
string GUID required

The contact identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
phone_type
string required
Enumeration:
LANDLINE
MOBILE
FAX
is_primary
boolean nullable

Defines whether this phone will be the primary one or not

Example:
true
number
string required

The phone number

Example:
22265566
country_code
string required

The phone country code

Example:
CYP
verification_required
boolean nullable

Defines whether phone verification will be required or not

Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The phone identifier

Example:
9d1df8ce-cecd-d335-2b44-2644c9576e6f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/phones HTTP/1.1 

Content-Type: application/json

{
    "is_primary": true,
    "number": "",
    "country_code": "GRC"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Contact Phone
PUT /contacts/{id}/phones/{phone_id}

Update the phone of an existing contact

Path variables

id
string GUID required

The contact identifer that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
phone_id
string GUID required

The phone identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
is_primary
boolean nullable

Defines whether the phone is the primary one or not

Example:
true
number
string nullable

The phone number

Example:
22265566
country_code
string nullable

The phone country code

Example:
CYP
verification_required
boolean nullable

Defines whether the phone needs to be verified or not

Default:
false
Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The phone identifier

Example:
9d1df8ce-cecd-d335-2b44-2644c9576e6f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Remove Contact Phone
DELETE /contacts/{id}/phones/{phone_id}

Removes a single contact phone.

Path variables

id
string GUID required

The contact identifier whose phone will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
phone_id
string GUID required

The phone identifier that will be removed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/phones/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 
Statement
GET /contacts/{id}/statement
GET /contacts/{id}/statement_details
POST /contacts/{id}/export_statement
Get Statement
GET /contacts/{id}/statement

Retrieves the account balance information for a specific Contact based on the selected period, for the signed-in organisation. Used in conjunction with Get Account Statement Details to produce a Contact statement.

Path variables

id
string GUID required

The contact identifier to retrieve account and wallet balances for

Example:
76D7A65ACCE45B2E68DFDCAD1E31269B

Request parameters

account_id
string optional

Contact’s account id to retrieve balance information for, semi-optional with currency_code

Example:
da60dd8f-b124-439d-a7fe-e1bdbd484c71
currency_code
string optional

Specify the 3-char account currency for which the statement will be produced, semi-optional with account_id. Default is the primary account’s currency

Example:
EUR
from_month
integer optional

Starting statement period month

Example:
3
to_month
integer optional

Ending statement period month

Example:
3
from_year
integer optional

Starting statement period year

Example:
2022
to_year
integer optional

Ending statement period year

Example:
2022

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string

Account unique identifier

Example:
c8079ee1-8081-4be1-ab09-5091f55b2d4e
number
string

Account number

Example:
A3900853
currency_code
string

Account 3-char currency code

Example:
EUR
period
Object

Statement period

month
Object

Statement period months

from
integer

Starting month

Example:
3
to
integer

Ending month

Example:
3
year
Object

Statement period year

from
integer

Starting year

Example:
2022
to
integer

Ending year

Example:
2022
opening_balance
number

Opening balances for account

Example:
34.04
closing_balance
number

Closing balances for account

Example:
31.65
total_credits
number

Total credited amount to the account for the selected period

Example:
8.99
total_debits
number

Total debited amount to the account for the selected period

Example:
2.72
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GK sample
GET https://sandbox.crm.com/backoffice/v1/contacts/76D7A65ACCE45B2E68DFDCAD1E31269B/statement?account_id=da60dd8f-b124-439d-a7fe-e1bdbd484c71&currency_code=EUR&from_month=3&to_month=3&from_year=2022&to_year=2022 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c8079ee1-8081-4be1-ab09-5091f55b2d4e",
    "number": "A3900853",
    "currency_code": "EUR",
    "period": {
        "month": {
            "from": 3,
            "to": 3
        },
        "year": {
            "from": 2022,
            "to": 2022
        }
    },
    "opening_balance": 34.04,
    "closing_balance": 31.65,
    "total_credits": 8.99,
    "total_debits": 2.72
}
GET https://sandbox.crm.com/backoffice/v1/contacts/76D7A65ACCE45B2E68DFDCAD1E31269B/statement?as_of_date=1635324343 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "type": "ACCOUNT",
            "id": "c8079ee1-8081-4be1-ab09-5091f55b2d4e",
            "number": "A3900853",
            "is_primary": true,
            "currency_code": "EUR",
            "opening_balances":                {
                    "balance": 34.94
                }
            
        },
        {
            "type": "WALLET",
            "id": "c8079ee1-8081-4be1-ab09-5091f55b2d4e",
            "number": "4349900943219923",
            "currency_code": "EUR",
            "opening_balances":                {
                    "open": 10.05,
                    "commerce": 23.99,
                    "balance": 34.94
                }
            
        }
        
    ]
}
Get Statement Details
GET /contacts/{id}/statement_details

Retrieves all the statement detail lines for a single Contact account, for the given period, used in conjunction with Get Accounts Statement API to create a Contact statement

Path variables

id
string GUID required

The contact identifier for which to retrieve account journals for

Example:
76D7A65ACCE45B2E68DFDCAD1E31269B

Request parameters

account_id
string optional

Contact’s account id to retrieve detail lines for, semi-optional with currency_code

Example:
da60dd8f-b124-439d-a7fe-e1bdbd484c71
currency_code
string optional

3-char account currency of the account, semi-optional with account_id

Example:
EUR
from_month
integer optional

Starting statement period month

Example:
3
to_month
integer optional

Ending statement period month

Example:
3
from_year
integer optional

Starting statement period year

Example:
2022
to_year
integer optional

Ending statement period year

Example:
2022

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Statement detail lines

Object
id
string

Account unique id

Example:
d2ea1d75-0805-4d8c-b212-f31064ee3bff
date
string epoch

Transaction date

Example:
2343342445
type
string

Type of financial transaction

Enumeration:
CREDIT
DEBIT
Example:
DEBIT
amount
number

Transaction amount

Example:
3.59
currency_code
string

3-char currency code of transaction

Example:
EUR
activity
Object

Financial activity information

type
string
Enumeration:
SETTLEMENT_PROCESS
PAYMENT
INVOICE
CREDIT_NOTE
REFUND
TOP_UP
TRANSFER
PASS_REDEMPTON
AD_HOC_RETURN
SPEND
AWARD
PURCHASE_CANCELLATION
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
number
string

The reference number of the transaction if available (e.g. reference number of a payment or a transfer)

Example:
90508992
id
string GUID

The activity entity unique id number (e.g. id of an invoice)

Example:
61c943c8-dfeb-4c09-a25c-b054f48bf244
details
string

Transaction details

Example:
Sally's Flower Shop
running_balance
string

Current running balance of account

Example:
12.84
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/76D7A65ACCE45B2E68DFDCAD1E31269B/statement_details?account_id=da60dd8f-b124-439d-a7fe-e1bdbd484c71&currency_code=EUR&from_month=3&to_month=3&from_year=2022&to_year=2022 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "d2ea1d75-0805-4d8c-b212-f31064ee3bff",
            "number": "A3900853",
            "date": "2343342445",
            "type": "DEBIT",
            "amount": 3.59,
            "currency_code": "EUR",
            "activity": {
                "type": "ACHIEVEMENT_CANCELLATION",
                "number": "90508992",
                "id": "61c943c8-dfeb-4c09-a25c-b054f48bf244"
            },
            "details": "Sally's Flower Shop",
            "running_balance": "12.84"
        }
    ]
}
Export Statement
POST /contacts/{id}/export_statement

Use this API to export the contact statement in PDF or CSV format to the user’s email, or send to the contact’s email address

Path variables

id
string required

The contact id to export statement for

Example:
da60dd8f-b124-439d-a7fe-e1bdbd484c71

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
account_id
string

Contact’s account id to export

Example:
da60dd8f-b124-439d-a7fe-e1bdbd484c71
currency_code
string

3-char account/wallet currency

Example:
EUR
from_month
integer

Statement period starting month

Example:
3
to_month
integer

Statement period ending month

Example:
3
from_year
integer

Statement period starting year

Example:
2022
to_year
integer

Statement period ending year

Example:
2022
format
string

How the statement will be sent (in which format)

Enumeration:
PDF
CSV
EMAIL

Sent to the Contact’s email address

PRINT
Example:
EMAIL

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/da60dd8f-b124-439d-a7fe-e1bdbd484c71/export_statement HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "account_id": "da60dd8f-b124-439d-a7fe-e1bdbd484c71",
    "currency_code": "EUR",
    "from_month": 3,
    "to_month": 3,
    "from_year": 2022,
    "to_year": 2022,
    "format": "EMAIL"
}
Applications Usage
GET /contacts/{id}/applications
DELETE /contacts/{id}/applications/{app_id}
List Applications Usage
GET /contacts/{id}/applications

List of applications that are used by a specific contact

Path variables

id
string GUID required

The contact (identifier) whose applications usage will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The application usage identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
platform
string

The platform on which the application was downloaded

Enumeration:
ANDROID
IOS
first_usage_date
integer epoch

The date on which the first uage was recorded

Example:
1598598647
application
Object

Details about the application

id
string GUID

The application identiier

Example:
af9c61d3-7685-e31f-3387-27c42858e868
name
string

The application name

Example:
Best Coffee App
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/applications HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "first_usage_date": 1598598647,
            "platform": "IOS",
            "application": {
                "id": "af9c61d3-7685-e31f-3387-27c42858e868",
                "name": "Best Coffee App"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Remove Applications Usage
DELETE /contacts/{id}/applications/{app_id}

Remove an application from a contact

Path variables

id
string GUID required

The contact (identifier) whose application usage will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
app_id
string GUID required

The application (identifier) usage record identifier that will be removed

Example:
57561166-6aa5-3ce5-2269-c38febe7e888

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/applications/57561166-6aa5-3ce5-2269-c38febe7e888 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Contact Identities
GET /contacts/{id}/identities
List Contact Identities
GET /contacts/{id}/identities

Retrieve a list of contact identities based on search criteria (e.g. all contact identities)

Path variables

id
string GUID required

The contact (identifier) whose identities will be retrieved

Example:
5fa7ff61-a960-cfa3-2f93-68a67058489a

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The contact identity identifier

Example:
09e4d464-3bae-1eab-1c7c-9166979300fd
username
string

The contact identity username

Example:
johndoe@crm.com
type
string

The contact identity type

Enumeration:
EMAIL_PASSWORD
EMAIL_OTP
PHONE_OTP
GOOGLE
FACEBOOK
MAC_ADDRESS
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/5fa7ff61-a960-cfa3-2f93-68a67058489a/identities HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "09e4d464-3bae-1eab-1c7c-9166979300fd",
            "username": "johndoe@crm.com",
            "type": "EMAIL_PASSWORD"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Customer Events
Achievement Events
POST /achievements
POST /achievements/{id}/cancel
GET /achievements
GET /achievements/{id}
GET /achievements/{id}/rewards
Create Achievement
POST /achievements

Create a new achievement customer event in posted life cycle state

Notes

CUSTOMER IDENTIFICATION

Customer identification can be achieved by providing one of the following attributes

  1. contact id - a unique contact identifier as specified in CRM.COM
  2. cim - a unique identification medium representing the customer (e.g. phone number, hashed card number)
  3. contact code - a unique contact code as specified in CRM.COM

Request headers

api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
id
string GUID nullable

The achievement customer event identifier

Max length: 32
Example:
CEEE83D6E0804A30966F684B0269AD91
contact_id
string GUID required nullable

The contact identifier that the achievement is created for

Max length: 32
Example:
79adca27-e50d-40d2-b025-e7d4710a1053
cim
string required nullable

The value for a single contact identification medium representing the customer that the achievement is created for

Example:
4A30966F684B0269AD91
contact_code
string

The contact code that the achievement is created for

reference_number
string nullable

The achievement reference number

Example:
RF000001
performed_on
integer epoch nullable

The date that the achievement was performed

Example:
1572423477
amount
number nullable

The amount related with the achievement

Example:
131.2
classification
Object nullable

The purchase classification

id
string GUID required nullable

The customer event classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string required nullable

The customer event classification name

Example:
Delivery Purchase
merchant_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
organisation_id
string GUID required nullable

The organisation that the achievement was submitted from. Merchant TAP and Organisation (id) are semi-optional

Example:
5eb64e17-154f-4e47-ab8b-14e56c0be3e8

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The achievement identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/achievements HTTP/1.1 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "contact_id": "79adca27-e50d-40d2-b025-e7d4710a1053",
    "classification": {
        "name": "Performance"
    },
    "organisation_id": "5eb64e17-154f-4e47-ab8b-14e56c0be3e8"
}
Cancel Achievement
POST /achievements/{id}/cancel

Cancels an existing achievement customer event and as a result any related awards will be reversed

Path variables

id
string GUID required

The achievement (identifier) that will be cancelled

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0

Request headers

api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The achievement identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/achievements/4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0/cancel HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Achievements
GET /achievements

Search for achievement customer events

Request parameters

contact_id
string GUID optional

The contact (identifier) who performed the achievement

Example:
CEEE83D6E0804A30966F684B0269AD91
contact_code
string optional

The contact code who performed the achievement

Example:
ABC1234
reference_number
string optional

The achievement reference number

Example:
REF1234
performed_date
integer epoch optional

Filter achievement events for which the performed date falls within a given date range (e.g. performed_date.[gte]=1618395497&performed_date.[lt]=1618395497)

Example:
1618395497
amount
number optional

Filter achievement events for which the related amount falls within a given amount range (e.g. amount.[gte]=0.99&amount.[lt]=1.99)

Example:
11.99
life_cycle_state
string optional

The life cycle state of the achievement event

Enumeration:
POSTED
CANCELLED
classification_id
string GUID optional

The classification related to the achievement customer event

Example:
a7792aa8-74c0-4cdb-8ea2-aa11b8fceaa6
organisation_id
string GUID optional

The organisation that the achievement customer event was performed

Example:
CEEE83D6E0804A30966F684B0269AD91
tap_id
string GUID optional

The transaction acquiring point that captured the achievement event

Example:
CEEE83D6E0804A30966F684B0269AD91
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The achievement identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string

The achievement reference number

Example:
REF1234
performed_on
integer epoch

The date on which the achievement was performed

Example:
1576486645
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
amount
number

The amount related to the achievement

Example:
1
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/achievements HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "reference_number": "REF1234",
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Doe",
                "code": "CO1234"
            },
            "account": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "ACR1234 John Doe",
                "number": "ACR1234"
            },
            "life_cycle_state": "POSTED",
            "classification": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Delivery"
            },
            "total_amount": 1,
            "organisation": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "Bravo Coffee"
            },
            "performed_on": 1576486645
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Achievement
GET /achievements/{id}

Get details for a single achievement customer event

Path variables

id
string GUID required

The achievement (identifier) that will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The achievement identifier

Example:
f22d4b76-8586-b982-e342-b16168e9c5f9
reference_number
string

The achievement reference number

Example:
REF001
code
string

A unique code assigned to the achievement

Example:
1234WER
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
performed_on
integer epoch

The date on which the achievement was performed

Example:
1576486645
amount
number

The amount related with the achievement

Example:
1.5
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
tap
Object

Details about the transaction acquiring point that captured such event

id
string GUID

The transaction acquiring point identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The transaction acquiring point name

Example:
ePOS
code
string

The transaction acquiring point code

Example:
TAP00012
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
rewards
Object

Information (dynamic) about the award/spend amounts

total_award_amount
number

The amount in real currency that was spent via the customer event

Example:
121.99
fees
Object

Information about the fees that were applied on achievement

total_fee_amount
number

The total fee amount (sum of all fee amounts)

Example:
2.54
wallet_credit_fee_amount
number

The wallet fee that was applied on provided awards

Example:
1.21
top_up
Object

Details about the customer event related top-up financial transaction

id
string GUID

The top-up identifier

Example:
f83054f2-b57d-4c2f-6ca0-f7822b5f0efa
code
string

The top-up code

Example:
QWS2234GSWS32424
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/purchases/CEEE83D6E0804A30966F684B0269AD91 HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "reference_number": "REF001",
    "life_cycle_state": "CANCELLED",
    "reduction_method": "BACK_END",
    "payment_medium_identifer": "424242",
    "performed_on": 1576486645,
    "total_net_amount": 1.59,
    "total_tax_amount": 0.41,
    "discount_amount": 0.5,
    "total_amount": 1.5,
    "requested_spend_amount": 1,
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Doe",
        "code": "CO1234"
    },
    "account": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "ACR1234 John Doe",
        "number": "ACR1234"
    },
    "organisation": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "Bravo Coffee"
    },
    "tap": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "ePOS",
        "code": "TAP00012"
    },
    "rewards": {
        "total_award_amount": 121.99,
        "total_spend_amount": 12.22,
        "total_automatic_spend_amount": 2.22,
        "total_instant_discount_amount": 4.49,
        "total_spend_request_amount": 4.51
    },
    "products": [
        {
            "product_sku": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "sku": "SKU00012",
                "name": "Cappuccino",
                "description": "Cappuccino Coffee"
            }
            "quantity": 1,
            "net_amount": 1.08,
            "tax_amount": 0.51,
            "total_amount": 1.59
        },
        {
            "product_family": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "Chocolates"
            },
            "quantity": 1,
            "net_amount": 1.08,
            "tax_amount": 0.51,
            "total_amount": 1.59
        }
    ]
}
List Achievement Rewards Breakdown
GET /achievements/{id}/rewards

Get reward details (awards/spends) for a specific achievement customer event

Path variables

id
string GUID required

The achievement (identifier) for which rewards details will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request parameters

type
string optional

Filter based on reward type

Enumeration:
AWARD
SPEND

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array

Details about the reward (award/spend) breakdown

Object
type
string

The reward type

Enumeration:
AWARD
SPEND
reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
spend_method
string

The reward spend method

Enumeration:
AUTOMATIC_SPEND
INSTANT
ON_REQUEST
amount
number

The award/spend amount

Example:
9.99
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/achievement/CEEE83D6E0804A30966F684B0269AD91/rewards HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "type": "AWARD",
            "reward_offer": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "1% cashback on all products"
            },
            "spend_method": "INSTANT_DISCOUNT",
            "amount": 9.99
        }
    ]
}
Purchase Events
POST /purchases
POST /purchases/{id}/cancel
GET /purchases
GET /purchases/{id}
GET /purchases/{id}/rewards
POST /purchases/ad_hoc_return
POST /purchases/batches
GET /purchases/batches
GET /purchases/batches/{id}
Create Purchase
POST /purchases

Create a new purchase customer event in posted life cycle state

Notes

CUSTOMER IDENTIFICATION

Customer identification can be achieved by providing one of the following attributes

  1. contact id - a unique contact identifier (usually GUID based)
  2. cim - a unique identification medium representing the customer (e.g. phone number, hashed card number)
  3. contact token - an OTP token as requested by a contact via CRM.COM applications
  4. contact code - a unique contact code (usually 8 or 16 characters long)
  5. contact (mask) card - a minimum set of card details (surname, exp date, last 4 digits), but still covered by PCI compliance
PRODUCT CORE BEHAVIOR

Product SKUs and Product Families will be created automatically if they are submitted in a purchase and do not exist in CRM.COM.

PURCHASE ESTIMATES FLOW

Integrating purchase estimates in a “submit purchase” flow that following APIs should be called

  1. POST /estimates/purchases
  2. POST /purchases by providing the estimates identifier as return from previous API call

Attribute “disable spends” from Purchase Estimates can be explicitly ovewritten by Submit Purchase.

Request headers

api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
id
string GUID nullable

The purchase customer event identifier

Max length: 32
Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
reference_number
string nullable

The purchase reference number

Example:
RF000001
estimation_id
string GUID nullable

The purchase estimation (identifier) that can be used instead of specifying (again) all purchase attributes

Example:
a68cfe78-153d-e7ad-a4b4-4d783f7e6219
reduction_method
string nullable

The reduction method that was applied on the related spend

Enumeration:
FRONT_END
BACK_END
performed_on
integer epoch nullable

The date that the customer event was performed

Example:
1572423477
disable_spends
boolean nullable

Defines whether spend resolution should be disabled or not (if disable spend requests, including instant spends, will not be taken into consideration)

Default:
false
Example:
true
payment_medium_identifier
string nullable

The unique identifier of the payment medium used in the purchase e.g. the first 8 digits of a credit card

Example:
42424242
contact_id
string GUID required nullable

The contact identifier that the purchase is created for

Max length: 32
Example:
79adca27-e50d-40d2-b025-e7d4710a1053
cim
string required nullable

The value for a single contact identification medium representing the contact that the purchase is created for.

  • This should be set to the pass code for purchases using gift passes
Example:
4A30966F684B0269AD91
contact_code
string required nullable

The contact code that the purchase is created for

Example:
12345CODE54321
contact_token
string required nullable

The OTP token that will identify the contact

Example:
123456
mask_card
Object required nullable
last4
string required nullable

The card’s last 4 digits

Example:
4242
expiration_month
integer required nullable

The card’s expiration month

Example:
10
expiration_year
integer required nullable

The card’s expiration year

Example:
2021
card_owner
Object required nullable

Details about the card owner

surname
string required nullable

The card’s owner surname

Example:
doe
spend_request
Object nullable

Information related with the spend request that should be created as part of the purchase

amount
number required nullable

The amount to be spent by the specified spend request in system currency

Example:
2.12
restrict_fully_covered
boolean nullable

Defines whether the purchase will be posted successfully only if requested spend amount is fully covered by the available wallet balance - applicable only for Front-End Reduction purchases and only when requested spend amount is specified

Example:
true
products
Array required nullable

The purchased products. Applicable and required when net/tax/total amounts are not provided

Object
product_sku
string required nullable

The purchased product sku (product sku and product family are semi-optional)

Example:
FREDESPR001
product_name
string nullable

The purchased product name

Example:
Freddo Espresso
product_family
string required nullable

The purchased product family (product sku and product family are semi-optional)

Example:
Chocolates
net_amount
number required

The purchased product net amount

Example:
14.15
tax_amount
number required

The purchased product vat amount

Example:
1.04
total_amount
number required

The purchased product total amount (net and vat amount)

Example:
15.19
quantity
integer nullable

The purchased quantity

Default:
1
Example:
2
merchant_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
outlet_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
organisation_id
string GUID required nullable

The organisation that the purchase was submitted from. Merchant/Venue TAP and Organisation (id) are semi-optional

Example:
5eb64e17-154f-4e47-ab8b-14e56c0be3e8
discount_amount
number nullable

The discount of the purchase

Example:
14.56
net_amount
number required nullable

The purchase net amount. Applicable when products (sku/family) are not provided

Example:
121.1
tax_amount
number required nullable

The purchase tax amount. Applicable when products (sku/family) are not provided

Example:
10.1
total_amount
number required nullable

The purchase total amount (net + tax - discount). Applicable when products (sku/family) are not provided

Example:
131.2
classification
Object nullable

The purchase classification

id
string GUID required nullable

The customer event classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string required nullable

The customer event classification name

Example:
Delivery Purchase
pass
Object nullable

Details about the pass

type
string

Pass type

Enumeration:
PROMOTION
GIFT
TOP_UP
Default:
PROMOTION
code
string required

The pass code. For Promotion passes - a Promotion pass will be generated and redeemed as part of the process, the contact_id should also be provided

Example:
SI8276333
pin
string

The pass assocaited pin (if applicable) should be set here for validation

  • If validation is successful, the Purchase Event will be created and wallet funds will be consumed
  • If validation is unsuccessful, the Purchase Event won’t be created and wallet funds won’t be consumed
Example:
1234
otp
string nullable

The pass one time password (if applicable) - not implemented yet for passes

Example:
445729
transaction_reference
string nullable

The transaction reference number that will be used for matching purchases (TP Match Mode)

Example:
795a-2dc4cc3f566f

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The purchase identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
reference_number
string

The purchase reference number (applicable only for Front-End Reduction)

Example:
RF123
total_award
number

The total award amount (applicable only for Front-End Reduction)

Example:
1.4
total_spend
number

The sum of all spends (instant discount, auto spends, spends on request). Applicable only for Front End Reduction

Example:
2.21
instant_discount
number

The spend related to instant discount. Applicable only for Front End Reduction

Example:
0.21
auto_spend
number

The spend related to auto spend requests. Applicable only for Front End Reduction

Example:
1.51
spend_on_request
number

The actual spent amount related to requested spend. Applicable only for Front End Reduction. If spend_request.amount has not been set - ‘null’ will be returned, if spend_request.amount has been set but no wallet funds can be consumed - 0.00 will be returned.

Example:
0.49
total_open_spend
number

The wallet’s open balance amount that was spent. Applicable only for Front End Reduction

Example:
0.09
total_commerce_spend
number

The wallet’s commerce balance amount that was spent. Applicable only for Front End Reduction

Example:
2.12
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Back-End Purchase
Front-End Purchase
Purchase with Estimates
Purchase with OTP Spend Request
Contact Reclaim Purchases

Create a (back-end reduction) purchase of classification Delivery with spend request and pass code redemption

POST https://sandbox.crm.com/backoffice/v1/purchases HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "O00123",
    "cim": "acd11adc-51cc-5d41-f1dd-f625a18b3ff3",
    "reduction_method": "BACK_END",
    "products": [
        {
            "product_sku": "10023401",
            "product_name": "Soda",
            "net_amount": 1.00,
            "tax_amount": 0.02,
            "total_amount": 1.02,
            "quantity": 1
        },
        {
            "product_sku": "20057809",
            "product_name": "Caramel Donut",
            "net_amount": 10.00,
            "tax_amount": 0.19,
            "total_amount": 10.19,
            "quantity": 10
        }
    ],
    "classification": {
        "name": "Delivery"
    },
    "spend_request": {
        "amount": 1.21
    },
    "pass": {
        "code": 1234
    },
    "outlet_tap": {
        "code": "8239"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "RF123",
    "total_award": null,
    "total_spend": null,
    "instant_discount": null,
    "auto_spend": null,
    "spend_on_request": null,
    "total_open_spend": null,
    "total_commerce_spend": null
}

Create a (front-end reduction) purchase of classification Delivery with spend request and pass code redemption

POST https://sandbox.crm.com/backoffice/v1/purchases HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "O00123",
    "contact_id": "acd11adc-51cc-5d41-f1dd-f625a18b3ff3",
    "reduction_method": "FRONT_END",
    "products": [
        {
            "product_sku": "10023401",
            "product_name": "Soda",
            "net_amount": 1.00,
            "tax_amount": 0.02,
            "total_amount": 1.02,
            "quantity": 1
        },
        {
            "product_sku": "20057809",
            "product_name": "Caramel Donut",
            "net_amount": 10.00,
            "tax_amount": 0.19,
            "total_amount": 10.19,
            "quantity": 10
        }
    ],
    "classification": {
        "name": "Delivery"
    },
    "spend_request": {
        "amount": 1.21
    },
    "pass": {
        "code": 1234
    },
    "outlet_tap": {
        "code": "8239"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "RF123",
    "total_award": 1.4,
    "total_spend": 1.21,
    "instant_discount": 0.21,
    "auto_spend": null,
    "spend_on_request": 1.00,
    "total_open_spend": 1.12,
    "total_commerce_spend": 0.09
}

Create a purchase based on a purchase estimates

POST https://sandbox.crm.com/backoffice/v1/purchases HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "RF000001",
    "estimation_id": "42c48837-7f19-6bfd-3789-7fd672c556c7",
    "reduction_method": "FRONT_END"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "41dc3d8a-5ab2-3dc8-83d5-33501eb1949f",
    "reference_number": "RF123",
    "total_award": 1.4,
    "total_spend": 2.21,
    "instant_discount": 0.21,
    "auto_spend": 1.51,
    "spend_on_request": 0.49,
    "total_open_spend": 1.12,
    "total_commerce_spend": 0.09
}

Create a purchase against a contact (OTP) token

POST /purchases HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json

{
    "id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
    "contact_token": "123456",
    "reduction_method": "FRONT_END",
    "products": [
        {
            "product_sku": "FREDESPR001",
            "product_name": "Freddo Espresso",
            "net_amount": 4.15,
            "tax_amount": 1.04,
            "total_amount": 5.19,
            "quantity": 2
        },
        {
            "product_sku": "ICL0001",
            "product_name": "Iced Caramel Latter",
            "net_amount": 5.15,
            "tax_amount": 1.04,
            "total_amount": 6.19,
            "quantity": 1
        }
    ],
    "discount_amount": 1.56,
    "merchant_tap": {
        "code": "EK123456"
    },
    "outlet_tap": {
        "code": "CD123456"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
    "reference_number": "RF000001",
    "total_award": 0.54,
    "total_spend": 1.72,
    "instant_discount": 0.21,
    "auto_spend": 1.51,
    "spend_on_request": 0.00
}

Create a purchase without a contact, and customer will reclaim it via scanning a QR/Barcode from mobile applications

POST https://sandbox.crm.com/backoffice/v1/purchases HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "O00123",
    "reduction_method": "BACK_END",
    "products": [
        {
            "product_sku": "10023401",
            "product_name": "Soda",
            "net_amount": 1.00,
            "tax_amount": 0.02,
            "total_amount": 1.02,
            "quantity": 1
        },
        {
            "product_sku": "20057809",
            "product_name": "Caramel Donut",
            "net_amount": 10.00,
            "tax_amount": 0.19,
            "total_amount": 10.19,
            "quantity": 10
        }
    ],
    "classification": {
        "name": "Delivery"
    },
    "outlet_tap": {
        "code": "8239"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
    "reference_number": "O00123",
    "total_award": null,
    "total_spend": null,
    "total_open_spend": null,
    "total_commerce_spend": null,
    "instant_discount": null,
    "auto_spend": null,
    "spend_on_request": null
}
Cancel Purchase
POST /purchases/{id}/cancel

Cancel an existing customer’s purchase and as a result any related awards/spends will be reversed

Path variables

id
string required

The purchase (identifier) that will be canceled

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The purchase identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Void Purchase
POST https://sandbox.crm.com/backoffice/v1/purchases/ccca2889-301b-40ad-aed9-9c3a78e6e50b/cancel HTTP/1.1 

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b"
}
List Purchases
GET /purchases

Search for purchase customer events

Request parameters

contact_id
string GUID optional

The contact identifier who performed the purchase

Example:
CEEE83D6E0804A30966F684B0269AD91
contact_code
string optional

The contact code who performed the purchase

Example:
ABC1234
reference_number
string optional

The purchase’s reference number

Example:
REF1234
life_cycle_state
string optional

The life cycle state of the customer event

Enumeration:
POSTED
CANCELLED
classification_id
string GUID optional

The classification related to the purchase customer event

Example:
a7792aa8-74c0-4cdb-8ea2-aa11b8fceaa6
organisation_id
string GUID optional

The organisation that the purchase customer event was performed

Example:
CEEE83D6E0804A30966F684B0269AD91
tap_id
string GUID optional

The transaction acquiring point that captured the customer event

Example:
CEEE83D6E0804A30966F684B0269AD91
from_total_amount
number optional

Filters customer events that have greater or equal total amount as specified

Example:
1.12
to_total_amount
number optional

Filters purchaes that have less or equal total amount as specified

Example:
1234.21
total_amount
string optional

Filter based on the total amount, which may fall within a given amount range. The value can be a string with an amount in numeric format. Each option must also include an operator. Use up to two options based on the required search (e.g. total_amount[gte]=12.99&total_amount[lt]=99.99).

Enumeration:
total_amount[gt]

Returns results where the total amount is greater than this value

total_amount[gte]

Returns results where the total amount is greater than or equal to this value

total_amount[lt]

Returns results where the total amount is less than this value

total_amount[lte]

Returns results where the total amount is less then or equal to this value

from_date
integer epoch optional

The date from which the purchase was performed.If not specified, then the last 10 purchases will be returned

Example:
11631602487
to_date
integer epoch optional

The date until which the purchase was performed

Example:
11631602487
performed_on
string optional

Filter based on the performed date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. performed_on[gte]=1618395497&performed_on[lt]=1618395497).

Enumeration:
performed_on[gt]

Returns results where the performed date is greater than this value

performed_on[gte]

Returns results where the performed date is greater than or equal to this value

performed_on[lt]

Returns results where the performed date is less than this value

performed_on[lte]

Returns results where the performed date is less then or equal to this value

is_ad_hoc_returned
boolean optional

Filter purchases that an ad hoc return was applied on them

Example:
true
ad_hoc_reference_number
string optional

Filter purchase based on the applied ad hoc return reference number

Example:
3276a89a-340e-e096-e79a-267dbddf8fca
transaction_reference
string optional

Filter based on transaction reference number

Example:
a64a-f1fcff0312fe
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The purchase identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string

The purchase’s reference number

Example:
REF1234
reduction_method
string

The reduction method that was applied on the related spend

Enumeration:
FRONT_END
BACK_END
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
total_net_amount
number

The purchase’s total net amount of all products’ net amount

Example:
1.51
total_tax_amount
number

The purchase’s total tax amount of all products’ tax amount

Example:
0.49
discount_amount
number

The purchase’s discount amount

Example:
1
total_amount
number

The purchase’s total amount

Example:
1
performed_on
integer epoch

The date on which the purchase was performed

Example:
1576486645
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/purchases HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmYmNmZjFmNS0zNDE2LTRkZWMtYTk3NC05YjA4MjBhMWQxNmIiLCJmdWxsX25hbWUiOiJHaW9yZ29zIFNha2thcyIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJjdXJyZW50X29yZ2FuaXNhdGlvbl9pZCI6IjViZjNmOTkyLTE4ZGQtNGYzYi05ZTc0LTAyYWRkNGU1ZmJkNSIsInByaW1hcnlfb3JnYW5pc2F0aW9uX2lkIjoiNWJmM2Y5OTItMThkZC00ZjNiLTllNzQtMDJhZGQ0ZTVmYmQ1IiwiY3VycmVudF9vcmdhbmlzYXRpb25fbmFtZSI6IlN0YWdpbmciLCJpc3MiOiJodHRwczovL3d3dy5jcm0uY29tIiwiZ3JvdXBzIjpbIlZJRVdfT1JHQU5JU0FUSU9OUyIsIk1BTkFHRV9PUkdBTklTQVRJT05fR1JPVVBTIiwiTUFOQUdFX09SR0FOSVNBVElPTlMiLCJBTExPV19UT19NQVNRVUVSQURFIiwiTUFOQUdFX1VTRVJTIiwiVklFV19VU0VSUk9MRVMiLCJNQU5BR0VfVVNFUlJPTEVTIiwiTUFOQUdFX0FQSUtFWVMiLCJERUxFVEVfUk9MTF9BUElLRVlTIiwiU0VUX1VQX0lOVEVHUkFUSU9OUyIsIlZJRVdfQ09OVEFDVFMiLCJNQU5BR0VfQ09OVEFDVFMiLCJNQU5BR0VfQUNDT1VOVFMiLCJTRVRfVVBfQ09OVEFDVFMiLCJTRVRfVVBfRklOQU5DSUFMUyIsIlZJRVdfRklOQU5DSUFMX1RSQU5TQUNUSU9OUyIsIk1BTkFHRV9GSU5BTkNJQUxfVFJBTlNBQ1RJT05TIiwiU0VUX1VQX0NVU1RPTUVSX0VWRU5UUyIsIlZJRVdfQ1VTVE9NRVJfRVZFTlRTIiwiTUFOQUdFX0NVU1RPTUVSX0VWRU5UUyIsIk1BTkFHRV9XQUxMRVRTIiwiVklFV19XQUxMRVRfVFJBTlNBQ1RJT05TIiwiTUFOQUdFX1dBTExFVF9UUkFOU0FDVElPTlMiLCJTRVRfVVBfUFJPRFVDVFMiLCJWSUVXX1JFV0FSRF9TQ0hFTUVTIiwiTUFOQUdFX1JFV0FSRF9TQ0hFTUVTIiwiVklFV19SRVdBUkRfT0ZGRVJTIiwiTUFOQUdFX1JFV0FSRF9PRkZFUlMiLCJTRVRfVVBfUkVXQVJEUyIsIk1BTkFHRV9QTEFURk9STSJdLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJnX3Nha2thc0Bjcm0uY29tIiwicHJpbWFyeV9vcmdhbmlzYXRpb25fbmFtZSI6IlN0YWdpbmciLCJ0eXBlIjoiYWNjZXNzIiwiZW1haWwiOiJnX3Nha2thc0Bjcm0uY29tIiwiaWF0IjoxNTkxMTc5NjM1LCJhdXRoX3RpbWUiOjE1OTExNzk2MzUsImV4cCI6MTU5MTE4NjgzNSwianRpIjoiYjRlZDk1MmUtNTI4Ny00ZWVmLWE4N2YtN2FhYTIwYmI0OGM5In0.iydf6Yi-H6v9P44Jb8htXayfbsXQxtHMOKquVqChpDM3IrVBolLS6mZ3dPCu7aoMejRK_OgIrriABC54Eh2yX7bgOiClZYhAQbdu3BAnykhiywEgrULD3RXkwS90gtOq-Uu8lE8b9Bm1lBcOr3HRwzlS8pweSh7nGR93i7XzxOwgRmfHMa17IC9t3GNKxVjyanG8gPTpvJI9f1nMvAad-y-rG4T90DiVJQ_uDCKmCJ0eCwgH_v4jQvcRnufW9F_7wI8VbYiIzYMuQC8f0DGZFif57FKl6_HQIYOH22JB6M9bQrJoEGDKWLqjfDEVerLiyyQf05zYvLTHvI_P6Gcn-Q

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "reference_number": "REF1234",
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Doe",
                "code": "CO1234"
            },
            "account": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "ACR1234 John Doe",
                "number": "ACR1234"
            },
            "life_cycle_state": "POSTED",
            "reduction_method": "BACK_END",
            "classification": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Delivery"
            },
            "total_net_amount": 1.51,
            "total_tax_amount": 0.49,
            "discount_amount": 1,
            "total_amount": 1,
            "organisation": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "Bravo Coffee"
            },
            "performed_on": 1576486645
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Purchase
GET /purchases/{id}

Get details for a single purchase customer event

Path variables

id
string GUID required

The purchase (identifier) that will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The purchase identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string

The purchase reference number

Example:
REF001
code
string

A unique code assigned to the purchase

Example:
1234WER
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
reduction_method
string

The reduction method that was applied on the related spend

Enumeration:
FRONT_END
BACK_END
payment_medium_identifier
string

The unique identifier of the payment medium used in the purchase e.g. the first 8 digits of a credit card

Example:
424242
performed_on
integer epoch

The date on which the purchase was performed

Example:
1576486645
total_net_amount
number

The purchase’s total net amount of all product lines’ net amount

Example:
1.59
total_tax_amount
number

The purchase’s total tax amount of all product lines’ tax amount

Example:
0.41
discount_amount
number

The purchase’s discount amount

Example:
0.5
total_amount
number

The purchase’s total amount

Example:
1.5
requested_spend_amount
number

The amount in real currency that was requested to be spend via the customer event

contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
tap
Object

Details about the transaction acquiring point that captured such event

id
string GUID

The transaction acquiring point identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The transaction acquiring point name

Example:
ePOS
code
string

The transaction acquiring point code

Example:
TAP00012
rewards
Object

Information (dynamic) about the award/spend amounts

total_award_amount
number

The amount in real currency that was spent via the customer event

Example:
121.99
total_spend_amount
number

The total amount (automatic + instant+ spend on request) in real currency that was spent via the customer event

Example:
12.22
total_automatic_spend_amount
number

The total amount in real currency that was spent automatically via the customer event

Example:
2.22
total_instant_discount_amount
number

The total amount in real currency that was spent instantly via the customer event

Example:
4.49
total_spend_request_amount
number

The total amount in real currency that was actually spent on request via the customer event (may differ than the requested_spend_amount)

Example:
4.51
ad_hoc_return
Object

Details of ad hoc return of goods

amount
number

The amount that the customer was debited due to ad hoc return of goods

Example:
12.34
ad_hoc_return_date
integer epoch

The date that ad hoc retun of goods was applied

Example:
1589987160
reference_number
string

The ad hoc return reference number

Example:
AHR001
return_amount
number

The amount that was returned

Example:
200.99
products
Array

Information about the purchase’s product line items

Object
product_sku
Object

Information about the product sku

id
string GUID

The product identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
sku
string

The product sku

Example:
SKU00012
name
string

The product name

Example:
Cappuccino
description
string

The product description

Example:
Cappuccino Coffee
product_family
Object

Information about the product family

id
string GUID

The product family identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The product family

Example:
Chocolates
quantity
integer

The quantity of the line item

Example:
1
net_amount
number

The net amount of the line item

Example:
1.08
tax_amount
number

The tax amount of the line item

Example:
0.51
total_amount
number

The total amount (net + tax) of the line item

Example:
1.59
pass
Object

Details about the customer event pass

id
string GUID

The pass identifier

Example:
83cbad41-86ee-4aa5-bc5a-6483094dceca
code
string

The pass code

Example:
132465798
invoice
Object

Details about the customer event related invoice

id
string GUID

The invoice identifier

Example:
93d4d954-0ffe-64d4-908f-732d2d79ce25
number
string

The invoice number

Example:
NUM1234
reference_number
string

The invoice reference number

Example:
REFNUM1234
credit_note
Object

Details about the customer event related credit note

id
string GUID

The credit note identifier

Example:
93d4d954-0ffe-64d4-908f-732d2d79ce25
number
string

The credit note number

Example:
NUM1234
reference_number
string

The credit note reference number

Example:
REFNUM123
fees
Object

Information about the fees that were applied on purchase

total_fee_amount
number

The total fee amount (sum of all fee amounts)

Example:
2.54
wallet_credit_fee_amount
number

The wallet fee that was applied on provided awards

Example:
1.21
wallet_debit_fee_amount
number

The wallet fee that was applied on spends

Example:
1.34
transaction_reference
string

The transaction reference number (TP Match Mode)

Example:
c855-b22208b42575
disable_spends
boolean

Defines whether spend resolution should be disabled or not (if disable spend requests, including instant spends, will not be taken into consideration)

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/purchases/CEEE83D6E0804A30966F684B0269AD91 HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "reference_number": "REF001",
    "life_cycle_state": "CANCELLED",
    "reduction_method": "BACK_END",
    "payment_medium_identifer": "424242",
    "performed_on": 1576486645,
    "total_net_amount": 1.59,
    "total_tax_amount": 0.41,
    "discount_amount": 0.5,
    "total_amount": 1.5,
    "requested_spend_amount": 1,
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Doe",
        "code": "CO1234"
    },
    "account": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "ACR1234 John Doe",
        "number": "ACR1234"
    },
    "organisation": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "Bravo Coffee"
    },
    "tap": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "ePOS",
        "code": "TAP00012"
    },
    "rewards": {
        "total_award_amount": 121.99,
        "total_spend_amount": 12.22,
        "total_automatic_spend_amount": 2.22,
        "total_instant_discount_amount": 4.49,
        "total_spend_request_amount": 4.51
    },
    "products": [
        {
            "product_sku": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "sku": "SKU00012",
                "name": "Cappuccino",
                "description": "Cappuccino Coffee"
            }
            "quantity": 1,
            "net_amount": 1.08,
            "tax_amount": 0.51,
            "total_amount": 1.59
        },
        {
            "product_family": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "Chocolates"
            },
            "quantity": 1,
            "net_amount": 1.08,
            "tax_amount": 0.51,
            "total_amount": 1.59
        }
    ]
}
List Purchase Rewards Breakdown
GET /purchases/{id}/rewards

Get reward details (awards/spends) for a specific purchase customer event

Path variables

id
string GUID required

The purchase (identifier) for which rewards details will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request parameters

type
string optional

The reward type

Enumeration:
AWARD
SPEND

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array

Details about the reward (award/spend) breakdown

Object
type
string

The reward type

Enumeration:
AWARD
SPEND
reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
spend_method
string

The reward spend method

Enumeration:
AUTOMATIC_SPEND
INSTANT
ON_REQUEST
amount
number

The award/spend amount

Example:
9.99
product
Object

The awarded product (free product)

type
string

The awarded product type

Enumeration:
SKU
BRAND
TYPE
FAMILY
id
string

The awarded product identifier

Example:
a82c9cb5-a774-f30d-2d9e-aca7f0561751
name
string

The awarded product name

Example:
Coffee
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/purchases/CEEE83D6E0804A30966F684B0269AD91/rewards HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "type": "AWARD",
            "reward_offer": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "1% cashback on all products"
            },
            "spend_method": "INSTANT_DISCOUNT",
            "amount": 9.99
        }
    ]
}
Ad Hoc Return of Goods
POST /purchases/ad_hoc_return

Performs an ad hoc return of goods for a speciifc customer

Notes

RETURN CORE BEHAVIOR

No purchase customer events will be cancelled

When an ad hoc return of goods transaction takes place, the customer wallet will be debited for an amount proportional based on the return amount, the identified purchase transaction amount and the award (on total transaction value) provided on that purchase.
debit amount = (return amount/purchase total amount)*award amount

Any spend amount on such purchase should be ignored, as the spend is an event that is triggered real-time and returning any spend amounts can be a complex process due to different spend conditions that apply on awards that the Customer has earned from previous purchases.

Request headers

api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string GUID required nullable

The contact id that the customer event is created for (either contact_id or cim must be specified)

Max length: 32
Example:
CEEE83D6E0804A30966F684B0269AD91
cim
string required nullable

The value for a single contact identification medium representing the customer event is created for (either contact_id or cim must be specified)

Example:
4A30966F684B0269AD91
amount
number required

The amount (real currency) of purchased goods that are returned

Example:
14.56
merchant_tap
Object

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
outlet_tap
Object

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
reference_number
string nullable

The ad hoc return reference number

Example:
RF123
ad_hoc_return_date
integer epoch nullable

The date that the ad hoc return is requested

Example:
1601636231

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The purchase identifier that ad hoc return is performed against

Example:
37ed4a1a-0e8f-4691-a8a0-636aea6e47c5
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2

Create return of goods using contact identifier

POST https://sandbox.crm.com/backoffice/v1/purchases/ad_hoc_return HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "contact_id": "41dc3d8a-5ab2-3dc8-83d5-33501eb1949f",
    "amount": 14.56,
    "merchant_tap": {
        "code": "EK123456"
    },
    "outlet_tap": {
        "code": "CD123456"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b"
}

Create return of goods using contact cim (e.g. hashed card number)

POST https://sandbox.crm.com/backoffice/v1/purchases/ad_hoc_return HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "cim": "82707d78dd30dcc18d03393f79824aa6a719ef909f16a4b3cdc46e09e0688e07",
    "amount": 14.56,
    "merchant_tap": {
        "code": "EK123456"
    },
    "outlet_tap": {
        "code": "CD123456"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b"
}
Purchase Events Batch
POST /purchases/batches

Create a new batch to submit a number of purchase events

Notes

CUSTOMER IDENTIFICATION

Customer identification can be achieved by providing one of the following attributes

  1. contact id - a unique contact identifier (usually GUID based)
  2. cim - a unique identification medium representing the customer (e.g. phone number, hashed card number)
  3. contact token - an OTP token as requested by a contact via CRM.COM applications
  4. contact code - a unique contact code (usually 8 or 16 characters long)
  5. contact (mask) card - a minimum set of card details (surname, exp date, last 4 digits), but still covered by PCI compliance

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
id
string GUID nullable

The batch unique identifier

Example:
65bd03bf-b33e-469d-a8cc-505654d3df49
name
string nullable

The batch name

Example:
EOD Events
events
Array required

A list of purchase events

Object
id
string GUID nullable

The purchase customer event identifier

Max length: 32
Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
contact_id
string GUID required nullable

The contact identifier that the purchase is created for (customer identification can be made either using contact_id, contact_code, cim or contact_token)

Max length: 32
Example:
79adca27-e50d-40d2-b025-e7d4710a1053
contact_code
string required nullable

The contact code that the purchase is created for (customer identification can be made either using contact_id, contact_code, cim or contact_token)

Example:
CD12345
cim
string required nullable

The value for a single contact identification medium representing the customer that the purchase is created for (customer identification can be made either using contact_id, contact_code, cim or contact_token)

Example:
4A30966F684B0269AD91
contact_token
string required nullable

The OTP token that will identify the contact (customer identification can be made either using contact_id, contact_code, cim or contact_token)

Example:
123456
mask_card
Object required nullable
last4
string required nullable

The card’s last 4 digits

Example:
4242
expiration_month
integer required nullable

The card’s expiration month

Example:
10
expiration_year
integer required nullable

The card’s expiration year

Example:
2021
card_owner
Object required nullable

Details about the card owner

surname
string required nullable

The card’s owner surname

Example:
doe
reference_number
string nullable

The purchase reference number

Example:
RF000001
payment_medium_identifier
string nullable

The unique identifier of the payment medium used in the purchase e.g. the first 8 digits of a credit card

Example:
42424242
performed_on
integer epoch nullable

The date that the customer event was performed

Example:
1572423477
reduction_method
string nullable

The reduction method that was applied on the related spend

Enumeration:
FRONT_END
BACK_END
products
Array required nullable

The purchased products. Applicable and required when net/tax/total amounts are not provided

Object
product_sku
string required nullable

The purchased product sku (product sku and product family are semi-optional)

Example:
FREDESPR001
product_name
string nullable

The purchased product name

Example:
Freddo Espresso
product_family
string required nullable

The purchased product family (product sku and product family are semi-optional)

Example:
Chocolates
net_amount
number required

The purchased product net amount

Example:
14.15
tax_amount
number required

The purchased product vat amount

Example:
1.04
total_amount
number required

The purchased product total amount (net and vat amount)

Example:
15.19
quantity
integer nullable

The purchased quantity

Default:
1
Example:
2
spend_request
Object nullable

Information related with the spend request that should be created as part of the purchase

amount
number required nullable

The amount to be spent by the specified spend request in system currency

Example:
2.12
restrict_fully_covered
boolean nullable

Defines whether the purchase will be posted successfully only if requested spend amount is fully covered by the available wallet balance - applicable only for Front-End Reduction purchases and only when requested spend amount is specified

Example:
true
merchant_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
outlet_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
organisation_id
string GUID required nullable

The organisation that the purchase was submitted from. Merchant/Venue TAP and Organisation (id) are semi-optional

Example:
5eb64e17-154f-4e47-ab8b-14e56c0be3e8
discount_amount
number nullable

The discount of the purchase

Example:
14.56
net_amount
number required nullable

The purchase net amount. Applicable when products (sku/family) are not provided

Example:
121.1
tax_amount
number required nullable

The purchase tax amount. Applicable when products (sku/family) are not provided

Example:
10.1
total_amount
number required nullable

The purchase total amount (net + tax - discount). Applicable when products (sku/family) are not provided

Example:
131.2
classification
Object nullable

The purchase classification

id
string GUID required nullable

The customer event classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string required nullable

The customer event classification name

Example:
Delivery Purchase
pass
Object nullable

Details about the pass

type
string

Pass type

Enumeration:
PROMOTION
GIFT
TOP_UP
Default:
PROMOTION
code
string required

The pass code. For Promotion passes - a Promotion pass will be generated and redeemed as part of the process, the contact_id should also be provided

Example:
SI8276333
pin
string

The pass assocaited pin (if applicable) should be set here for validation

  • If validation is successful, the Purchase Event will be created and wallet funds will be consumed
  • If validation is unsuccessful, the Purchase Event won’t be created and wallet funds won’t be consumed
Example:
1234
otp
string nullable

The pass one time password (if applicable) - not implemented yet for passes

Example:
445729
disable_spends
boolean nullable

Defines whether spend resolution should be disabled or not (if disable spend requests, including instant spends, will not be taken into consideration)

Default:
false
Example:
true
estimation_id
string GUID nullable
Example:
a68cfe78-153d-e7ad-a4b4-4d783f7e6219
transaction_reference
string nullable

The transaction reference number that will be used for matching purchases (TP Match Mode)

Example:
4932-df54f3f92c65

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The batch identifier

Example:
65bd03bf-b33e-469d-a8cc-505654d3df49
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/purchases/batches HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "id": "65bd03bf-b33e-469d-a8cc-505654d3df49",
    "name": "EOD Events",
    "events": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "contact_id": "79adca27-e50d-40d2-b025-e7d4710a1053",
            "cim": "4A30966F684B0269AD91",
            "contact_token": "123456",
            "reference_number": "RF000001",
            "payment_medium_identifier": "42424242",
            "performed_on": 1572423477,
            "reduction_method": "FRONT_END",
            "products": [
                {
                    "product_sku": "FREDESPR001",
                    "product_name": "Freddo Espresso",
                    "product_family": "Chocolates",
                    "net_amount": 14.15,
                    "tax_amount": 1.04,
                    "total_amount": 15.19,
                    "quantity": 2
                }
            ],
            "spend_request": {
                "amount": 2.12
            },
            "merchant_tap": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "code": "TAP001"
            },
            "outlet_tap": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "code": "TAP002"
            },
            "organisation_id": "5eb64e17-154f-4e47-ab8b-14e56c0be3e8",
            "discount_amount": 14.56,
            "net_amount": 121.1,
            "tax_amount": 10.1,
            "total_amount": 131.2,
            "classification": {
                "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                "name": "Delivery Purchase"
            },
            "pass": {
                "code": "1231231231231231",
                "otp": "2345"
            }
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "65bd03bf-b33e-469d-a8cc-505654d3df49"
}
List Batches
GET /purchases/batches

Get a list of purchase batches and process status

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The batch identifier

Example:
65bd03bf-b33e-469d-a8cc-505654d3df49
name
string

The batch name

Example:
EOD File
start_date
integer epoch

The date on which the batch was performed

Example:
1606814571
event_count
integer

The number of items submitted

Example:
2
event_success
integer

The number of events that were successfully processed

Example:
1
event_failure
integer

The number of events that were failed to be processed

Example:
1
processed
integer

The number of events that were processed

Example:
2
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/purchases/batches HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "65bd03bf-b33e-469d-a8cc-505654d3df49",
            "name": "EOD File",
            "start_date": 1606814571,
            "event_count": 1,
            "event_success": 1,
            "event_failure": 1,
            "processed": 1
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Batch
GET /purchases/batches/{id}

Retrieve details for a specific batch of purchase events

Path variables

id
string GUID required

The batch (identifier) that will be retrieved

Example:
65bd03bf-b33e-469d-a8cc-505654d3df49

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The batch identifier

Example:
65bd03bf-b33e-469d-a8cc-505654d3df49
name
string

The batch name

Example:
EOD Batch
start_date
integer epoch

The date on which the batch was performed

Example:
1619533256
events
Array

A list of all processed purchase events

Object
id
string GUID

The purchase event identifier

Example:
65bd03bf-b33e-469d-a8cc-505654d3dfQQ
reference_number
string

The purchase event reference number

Example:
RF000001
processed_at
integer epoch

The time that the purchase event was processed

Example:
1606814160
process_status
string

The status of the processed purchase event

Enumeration:
SUCCESS
ERROR
PENDING
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/purchases/batches/65bd03bf-b33e-469d-a8cc-505654d3df49 HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "65bd03bf-b33e-469d-a8cc-505654d3df49",
    "name": "EOD Batch",
    "start_date": 1606814160,
    "events": [
        {
            "id": "65bd03bf-b33e-469d-a8cc-505654d3dfQQ",
            "reference_number": "RF000001",
            "processed_at": 1606814160,
            "process_status": "PENDING"
        }
    ]
}
Referral Events
POST /referrals/{id}/cancel
GET /referrals
GET /referrals/{id}
Cancel Referral
POST /referrals/{id}/cancel

Cancel an existing customer’s referral and as a result any related awards will be reversed

Path variables

id
string required

The referral (identifier) that will be canceled

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The referral event identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /referrals/CEEE83D6E0804A30966F684B0269AD91/cancel HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91"
}
List Referrals
GET /referrals

Search for referral customer events

Request parameters

referred_contact_id
string GUID optional

The referred contact identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
referred_by_contact_id
string GUID optional

The referred by contact identifier

reference_number
string optional

The referral’s reference number

Example:
REF1234
from_date
integer epoch optional

The date from which the referral was performed

to_date
integer epoch optional

The date until which the referral was performed

performed_on
string optional

Filter based on the performed date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. performed_on[gte]=1618395497&performed_on[lt]=1618395497).

Enumeration:
performed_on[gt]

Returns results where the performed date is greater than this value

performed_on[gte]

Returns results where the performed date is greater than or equal to this value

performed_on[lt]

Returns results where the performed date is less than this value

performed_on[lte]

Returns results where the performed date is less then or equal to this value

life_cycle_state
string optional

The life cycle state of the customer event

Enumeration:
POSTED
CANCELLED
organisation_id
string GUID optional

The organisation that the referral customer event was performed

Example:
CEEE83D6E0804A30966F684B0269AD91
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The referral identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string

The referral reference number

Example:
REF1234
referred_contact
Object

Details about the referred contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Doe
code
string

The contact code

Example:
CO1234
referred_account
Object

Details about the referred contact’s account

id
string GUID

The account identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account number

Example:
ACR1234
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
performed_on
integer epoch

The date on which the referral was performed

Example:
1576486645
referred_by_contact
Object

Details about the referred by contact

id
string GUID

The contact identifier

Example:
7db94d8b-4cbc-a7cc-9dc8-48ef68f9bf36
name
string

The contact name

Example:
Jane Doe
code
string

The contact code

Example:
JD987
referred_by_account
Object

Details about the referred by contact’s account

id
string GUID

The account identifier

Example:
9a0eab8b-d592-3039-9705-be3708d4f8cf
name
string

The account name

Example:
AR456 Jane Doe
number
string

The account number

Example:
AR456
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/referrals HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CEEE83D6E0804A30966F684B0269AD91",
            "reference_number": "REF1234",
            "referred_contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Doe",
                "code": "CO1234"
            },
            "referred_account": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "ACR1234 John Doe",
                "number": "ACR1234"
            },
            "life_cycle_state": "CANCELLED",
            "classification": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Delivery"
            },
            "organisation": {
                "id": "CEEE83D6E0804A30966F684B0269AD91",
                "name": "Bravo Coffee"
            },
            "performed_on": 1576486645,
            "referred_by_contact": {
                "id": "7db94d8b-4cbc-a7cc-9dc8-48ef68f9bf36",
                "name": "Jane Doe",
                "code": "JD987"
            },
            "referred_by_account": {
                "id": "9a0eab8b-d592-3039-9705-be3708d4f8cf",
                "name": "AR456 Jane Doe",
                "number": "AR456"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Referral
GET /referrals/{id}

Get details for a single referral customer event

Path variables

id
string GUID required

The referral event (identifier) that will be retrieved

Example:
CEEE83D6E0804A30966F684B0269AD91

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The referral identifier

Example:
CEEE83D6E0804A30966F684B0269AD91
reference_number
string

The referral reference number

Example:
REF001
life_cycle_state
string

The export definition status

Enumeration:
POSTED
CANCELLED
performed_on
integer epoch

The date on which the referral was made

Example:
1576486645
referred_contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
referred_account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
rewards
Object

Information (dynamic) about the award/spend amounts

total_award_amount
number

The amount in real currency that was spent via the customer event

Example:
121.99
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
referred_by_contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
referred_by_account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/referrals/CEEE83D6E0804A30966F684B0269AD91 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CEEE83D6E0804A30966F684B0269AD91",
    "reference_number": "REF001",
    "life_cycle_state": "CANCELLED",
    "performed_on": 1576486645,
    "referred_contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Doe",
        "code": "CO1234"
    },
    "referred_account": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "ACR1234 John Doe",
        "number": "ACR1234"
    },
    "organisation": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "name": "Bravo Coffee"
    },
    "rewards": {
        "total_award_amount": 121.99
    },
    "classification": {
        "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
        "name": "Delivery Purchase"
    },
    "referred_by_contact": {
        "id": "b47cc2a3-6e00-b826-6bb5-48849e222e2a",
        "name": "Jane Doe",
        "code": "45679"
    },
    "referred_by_account": {
        "id": "0a1c62c3-75cc-7b65-d7c8-9ce59f7ad6cc",
        "name": "AR567 Jane Doe",
        "number": "AR567"
    }
}
Devices
POST /devices
PUT /devices/{id}
DELETE /devices/{id}
GET /devices
GET /devices/{id}
GET /devices/{id}/history
POST /devices/{id}/ownership
Create Device
POST /devices

Create a new device. Only inventory items can be created.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
serial_number
string nullable

The device’s serial number

Example:
STB123456
electronic_id
string nullable

The device electronic id details

Example:
I243WER
product_id
string GUID nullable

The device’s product (identifier) - product must be of traceable physical good classification

Example:
f4b9dc04-b06f-1f57-bb9a-a845851b91e8
warehouse_id
string GUID required nullable

The warehouse (identifier) at which the device will be located, required only when devices are imported to a warehouse

Example:
d538824d-7efe-3f9d-5d11-701efca5fe40
contact_id
string GUID required nullable

The contact (identifier) that owns such device, required only when a contact registers his/her own device

Example:
81dd0800-be43-d43a-a727-77d6c7606036
spatial_location
string nullable

The spatial location of the device (when located in the warehouse)

Example:
1C
characteristics
Array nullable

The device characteristics (specified per product, product type or device)

Object
key
string required

The characteristic’s key which is uque across the set of configured characteristics

Example:
static_ip
value
string required

The actual value of the characteristic.

Example:
10.10.01.10
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
status_id
string GUID nullable

The device status

Example:
9af58460-b0e8-54f8-f15b-c96267fd8f52

Responses

200 OK

The request has succeeded

Body
Object
id
string

The unique identifier of the new device

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/devices HTTP/1.1 

Content-Type: application/json

{
    "product_id": "f4b9dc04-b06f-1f57-bb9a-a845851b91e8",
    "serial_number": "STB123456",
    "electronic_id": "",
    "contact_id": "81dd0800-be43-d43a-a727-77d6c7606036",
    "warehouse_id": "d538824d-7efe-3f9d-5d11-701efca5fe40",
    "spatial_location": "1C",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E"
}
Update Device
PUT /devices/{id}

Update a single device

Path variables

id
string GUID required

The device (identifier) to be updated

Example:
0b8e03c1-01e4-9c44-533a-d55b9ab0821e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
state
string nullable

The device’ state

Enumeration:
NEW
USED
RENTED
BLOCKED
spatial_location
string nullable

The spatial location of the device

Example:
1D
characteristics
Array nullable

The device characteristics (specified per product, product type or device)

Object
key
string required

The characteristic’s key which is uque across the set of configured characteristics

Example:
static_ip
value
string required

The actual value of the characteristic.

Example:
10.10.01.10
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
status_id
string GUID nullable

The device status

Example:
9af58460-b0e8-54f8-f15b-c96267fd8f52

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The device identifer

Example:
0b8e03c1-01e4-9c44-533a-d55b9ab0821e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/devices/0b8e03c1-01e4-9c44-533a-d55b9ab0821e HTTP/1.1 

Content-Type: application/json

{
    "state": "BLOCKED",
    "spatial_location": "1D",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0b8e03c1-01e4-9c44-533a-d55b9ab0821e"
}
Delete Device
DELETE /devices/{id}

Delete a single device

Path variables

id
string GUID required

The device (identifier) to be removed

Example:
f42971d4-cfcb-963b-6213-7e2b8c82b30c

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/devices/f42971d4-cfcb-963b-6213-7e2b8c82b30c HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 
List Devices
GET /devices

Returns a list of devices

Request parameters

search_value
string optional

Search for devices using their serial number, mac address or electronic ID

Example:
STB809403222
state
string optional

Filter based on device’s state

Enumeration:
NEW
USED
RENTED
BLOCKED
serial_number
string optional

Filter based on serial number

Example:
SN09234WE
electronic_id
string optional

Filter based on electronic id

Example:
1234WER
mac_address
string optional

Filter based on mac address

Example:
00:00:5e:00:53:af
subscription_ids
array of string optional

Return devices of a subscription i.e they were added to a subscirption and might provision at least one service

Collection format: csv
contact_id
string GUID optional

Filter based on the contact that owns/bought/brought/rented such devices

Example:
e3af8d33-b972-3a8a-d5ef-f5aa7de6dd61
warehouse_id
string GUID optional

Fitler based on the warehouse that the device is located in

Example:
9ec6ae6f-d824-e2fb-19bb-e91dd63bade8
organisation_id
string GUID optional

Filter based on the organisation that owns such devices

Example:
51283409-d80c-1a55-2514-892a9f746684
integration_id
string GUID optional

Filter based on the integrator (e.g. provisioning provider) that provisions the device

Example:
fda7c2a5-7012-61c3-44b1-c5617a415265
can_be_rented
boolean optional

If set to true, then list all warehouse devices that can be provded to contacts as rentals i.e such devices have a rental price in the product catalogue. It is important to note that only devices located in the business’s warehouse are returned

Example:
true
status_id
string GUID optional

Filter based on device status

Example:
4e99e182-2477-0814-97a1-ce1e227ce3d5
include_application
boolean optional

Defines whether Application details should be returned or not

Example:
false
include_wifi
boolean optional

Defines whether WiFi platform details should be returned or not

Example:
true
include_subscription
boolean optional

Defines whether subscription and enabled services should be returned or not

Example:
true
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_characteristics
boolean optional

If set to True, then device characteristics are also returned

Default:
false
Example:
true
product_id
string GUID optional
Example:
8c28baea-7a99-90a2-1f6a-a0a263a009c3
is_reserved
boolean optional

Defines whether only reserved devices will be retrieved or not

Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The device identifier

Example:
f9ce56ed-f1ce-a8f1-f9e8-e1db5fb2cb33
state
string

The device’ state

Enumeration:
NEW
USED
RENTED
BLOCKED
serial_number
string

The device’s serial number (Application/Inventory Devices)

Example:
STB123456
application
Object

Details about the application

id
string GUID

The application identiier

Example:
af9c61d3-7685-e31f-3387-27c42858e868
name
string

The application name

Example:
Best Coffee App
provided_on
integer epoch

The date from which the device is located at the contact’s premises (Inventory Devices)

Example:
1642770980
product
Object
id
string GUID

The product identifier

Example:
e283a863-18e1-7cae-48c4-7433bf28cf97
sku
string

The product SKU code

Example:
ABC-12345
name
string

The product name

Example:
ABC
owned_by
Object

Details about the device’s ownership

type
string

The ownership type

Enumeration:
BUSINESS
RETAILER
CONTACT
id
string GUID

The device owner identifier

Example:
5f67324c-1076-618b-8d29-012efde9485e
name
string

The name of the device owner

Example:
CRM
enabled_services
Array

Details about the enabled services for the device (Inventory Devices)

Object

Details about the enabled services for the device

id
string

The enabled service identifier

life_cycle_state
string

The enabled service life cycle state

product
Object

Details about a product

id
string GUID

The product identifier

Example:
a0f79973-d4b3-db89-4276-cb4abcccd842
sku
string

The product SKU code

Example:
STB
name
string

The product name

Example:
Set-top-box
characteristics
Array

The product measurement unit

Object
key
string
value
string
label
string
subscription
Object
id
string GUID

The subscription identifier

Example:
5535e087-3e27-d2c8-249f-54fe0c1307a4
code
string

The subscription code

Example:
SUB001
provisioning
Object

Details about the integration

id
string GUID

The integration identifier

Example:
81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4
name
string

The integration name

Example:
UniFi
wifi
Object

Details about the device WiFi platform status

status
string

The current WiFi status of the device

Enumeration:
ONLINE
OFFLINE
last_auth_date
string epoch

The last time that the device was WiFi authorized

Example:
1642767506
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
electronic_id
string

Details about device eletronic id

characteristics
Array

The device characteristics (specified per product, product type or device)

Object
key
string

The characteristic’s key which is uque across the set of configured characteristics

Example:
static_ip
value
string

The actual value of the characteristic.

Example:
10.10.01.10
label
string

The characteristic’s label

Example:
Static IP
status
Object

The device status

id
string GUID

The device status identifier

Example:
f39fb666-0856-f132-8abb-946f2c7ea2e9
name
string

The device status name

Example:
new status
is_reserved
boolean

Defines whether the device is reserved or not

Example:
true
warehouse
Object

The warehouse at which the device is located. Onyl available when the device is located at the business’s warehouse

id
string

Warrhsoue identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

Warehouse name

Example:
Main
reserved_by
Object

The business entity from which the device is reserved

type
string

The business entity from which the device is reserved for

Enumeration:
ORDERS
INVOICES
SERVICE_REQUESTS
id
string GUID

The business entity identifier that such device is reserved by

Example:
ccdcede0-066e-4412-b98d-72032c18e32d
number
string

The business entity number that such device is reserved by

Example:
N12345
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/devices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "f9ce56ed-f1ce-a8f1-f9e8-e1db5fb2cb33",
            "state": "BLOCKED",
            "serial_number": "STB123456",
            "application": {
                "id": "af9c61d3-7685-e31f-3387-27c42858e868",
                "name": "Best Coffee App"
            },
            "provided_on": 1642770980,
            "product": {
                "id": "e283a863-18e1-7cae-48c4-7433bf28cf97",
                "sku": "ABC-12345",
                "name": "ABC"
            },
            "owned_by": {
                "type": "RETAILER",
                "id": "5f67324c-1076-618b-8d29-012efde9485e",
                "name": "CRM"
            },
            "enabled_services": [
                {
                    "id": "",
                    "life_cycle_state": "",
                    "product": {
                        "id": "a0f79973-d4b3-db89-4276-cb4abcccd842",
                        "sku": "STB",
                        "name": "Set-top-box",
                        "characteristics": [
                            {
                                "key": "",
                                "value": "",
                                "label": ""
                            }
                        ]
                    }
                }
            ],
            "subscription": {
                "id": "5535e087-3e27-d2c8-249f-54fe0c1307a4",
                "code": "SUB001"
            },
            "provisioning": {
                "id": "81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4",
                "name": "UniFi"
            },
            "wifi": {
                "status": "OFFLINE",
                "last_auth_date": "1642767506"
            },
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ],
            "electronic_id": "",
            "characteristics": [
                {
                    "key": "static_ip",
                    "value": "10.10.01.10",
                    "label": "Static IP"
                }
            ],
            "status": {
                "id": "f39fb666-0856-f132-8abb-946f2c7ea2e9",
                "name": "new status"
            },
            "is_reserved": "true",
            "warehouse": {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "name": "Main"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Device
GET /devices/{id}

Retrieves a specific device

Path variables

id
string GUID required

The device (identifier) to be retrieved

Example:
c39c6c23-319f-ef74-37cd-9b7878992fc1

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
id
string

The device identifier

Default:
GUID
Example:
c39c6c23-319f-ef74-37cd-9b7878992fc1
state
string

The device’ state

Enumeration:
NEW
USED
RENTED
BLOCKED
serial_number
string

The device serial number

Example:
2049-3630
electronic_id
string

The device electronic id

Example:
123WER
mac_address
string

The device’s MAC address

Example:
00:00:5e:00:53:af
platform
string

The device’s operation platform (Application Devices)

Enumeration:
IOS
ANDROID
BROWSER
OTHER
registration_token
string

The device’s registration token for push notifications

Example:
4e11bef819b8ae9af08d
registration_date
integer epoch

The date that such device was registered by the contact

Example:
1642758418
application
Object

Details about the application

id
string GUID

The application identiier

Example:
af9c61d3-7685-e31f-3387-27c42858e868
name
string

The application name

Example:
Best Coffee App
wifi
Object

Details about the device WiFi platform status

status
string

The current WiFi status of the device

Enumeration:
ONLINE
OFFLINE
last_auth_date
string epoch

The last time that the device was WiFi authorized

Example:
1642767506
spatial_location
string

The device’s spatial location when located in a warehouse

Example:
1C
product
Object
id
string GUID

The product identifier

Example:
e283a863-18e1-7cae-48c4-7433bf28cf97
sku
string

The product SKU code

Example:
ABC-12345
name
string

The product name

Example:
ABC
owned_by
Object

Details about the device’s ownership

type
string

The ownership type

Enumeration:
BUSINESS
RETAILER
CONTACT
id
string GUID

The device owner identifier

Example:
5f67324c-1076-618b-8d29-012efde9485e
name
string

The name of the device owner

Example:
CRM
order
Object

The order from which the device was sold to the contact

id
string GUID

The order identifier

Example:
85328234-c8a7-4337-a574-89cfb6ec518e
number
string

The order number

Example:
O000234
enabled_services
Array

Details about the services that the device is enabled to

Object

Details about the enabled services for the device

id
string

The enabled service identifier

life_cycle_state
string

The enabled service life cycle state

product
Object

Details about a product

id
string GUID

The product identifier

Example:
a0f79973-d4b3-db89-4276-cb4abcccd842
sku
string

The product SKU code

Example:
STB
name
string

The product name

Example:
Set-top-box
characteristics
Array

The product measurement unit

Object
key
string
value
string
label
string
subscription
Object
id
string GUID

The subscription identifier

Example:
5535e087-3e27-d2c8-249f-54fe0c1307a4
code
string

The subscription code

Example:
SUB001
provisioning
Object

Details about the integration

id
string GUID

The integration identifier

Example:
81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4
name
string

The integration name

Example:
UniFi
characteristics
Array

The device characteristics (specified per product, product type or device)

Object
key
string

The characteristic’s key which is uque across the set of configured characteristics

Example:
static_ip
value
string

The actual value of the characteristic.

Example:
10.10.01.10
label
string

The characteristic’s label

Example:
Static IP
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
status
Object

The device status

id
string GUID

The device status identifier

Example:
f39fb666-0856-f132-8abb-946f2c7ea2e9
name
string

The device status name

Example:
new status
is_reserved
boolean

Defines whether the device is reserved or not

Example:
true
reserved_by
Object

The business entity from which the device is reserved

type
string

The business entity from which the device is reserved for

Enumeration:
SERVICE_REQUESTS
ORDERS
INVOICES
id
string

The business entity identifier that such device is reserved by

Example:
da8aaf6a-ac3e-ee44-4760-a3b4084b15f4
number
string

The business entity number that such device is reserved by

Example:
N1234
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/devices/c39c6c23-319f-ef74-37cd-9b7878992fc1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c39c6c23-319f-ef74-37cd-9b7878992fc1",
    "state": "RENTED",
    "mac_address": "00:00:5e:00:53:af",
    "platform": "IOS",
    "registration_token": "4e11bef819b8ae9af08d",
    "registration_date": 1642758418,
    "application": {
        "id": "af9c61d3-7685-e31f-3387-27c42858e868",
        "name": "Best Coffee App"
    },
    "wifi": {
        "status": "OFFLINE",
        "last_auth_date": "1642767506"
    },
    "serial_number": "2049-3630",
    "spatial_location": "1C",
    "product": {
        "id": "e283a863-18e1-7cae-48c4-7433bf28cf97",
        "sku": "ABC-12345",
        "name": "ABC"
    },
    "warehouse": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Nicosia headquarters"
    },
    "ownership": {
        "type": "CONTACT",
        "id": "5f67324c-1076-618b-8d29-012efde9485e",
        "name": "CRM"
    },
    "order": {
        "id": "",
        "number": ""
    },
    "enabled_services": [
        {
            "id": "",
            "life_cycle_state": "",
            "product": {
                "id": "a0f79973-d4b3-db89-4276-cb4abcccd842",
                "sku": "STB",
                "name": "Set-top-box",
                "measurement_unit": "MB"
            }
        }
    ],
    "subscription": {
        "id": "5535e087-3e27-d2c8-249f-54fe0c1307a4",
        "code": "SUB001"
    },
    "provisioning": {
        "id": "81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4",
        "name": "UniFi"
    },
    "custom_fields": [
        {
            "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a",
            "key": "back_office",
            "label": "Back Office",
            "description": "The account's back office code",
            "tooltip": "",
            "visible": true,
            "field": "AMOUNTS",
            "entity": "ORDERS"
        }
    ],
    "electronic_id": ""
}
Get Device History
GET /devices/{id}/history

Retrieves the history of a specific device

Path variables

id
string GUID required

The device (identifier) of which history will be retrieved

Example:
3ef38763-2d6b-fb41-5c22-79989fa90bae

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The historical action identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
action
string

The action that was performed

Enumeration:
STOCK_IN
STOCK_OUT
STOCK_ADJUSTMENT
STOCK_MOVEMENT
SALE
RETURN
RENT
TRANSFER
OWN_DEVICE
performed_on
integer epoch

The date on which such action was performed

Example:
1618861892
performed_by
Object

Details about the user/contact that performed such action

type
string

Defines who made such action

Enumeration:
CONTACT
USER
id
string GUID

The performer identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The performer full name

Example:
Jane Smith
username
string

The performer username (user related)

Example:
janesmith@crm.com
origin
Object

Details about the owner of a device (history)

type
string

Defines the historical entity type

Enumeration:
CONTACT
ORGANISATION
SUBSCRIPTION
WAREHOUSE
id
string GUID

Defines the historical entity identifier

Example:
07d737e8-d20c-08c5-7a2a-6c7f247b13a5
value
string

Defines the historical entity value

Example:
JS01
destination
Object

Details about the owner of a device (history)

type
string

Defines the historical entity type

Enumeration:
CONTACT
ORGANISATION
SUBSCRIPTION
WAREHOUSE
id
string GUID

Defines the historical entity identifier

Example:
07d737e8-d20c-08c5-7a2a-6c7f247b13a5
value
string

Defines the historical entity value

Example:
JS01
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/devices/3ef38763-2d6b-fb41-5c22-79989fa90bae/history HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "action": "RETURN",
            "performed_on": 1618861892,
            "performed_by": {
                "type": "USER",
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "name": "Jane Smith",
                "username": "janesmith@crm.com"
            },
            "origin": {
                "type": "WAREHOUSE",
                "id": "07d737e8-d20c-08c5-7a2a-6c7f247b13a5",
                "value": "JS01"
            },
            "destination": {
                "type": "ORGANISATION",
                "id": "07d737e8-d20c-08c5-7a2a-6c7f247b13a5",
                "value": "JS01"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Device Ownership Transaction
POST /devices/{id}/ownership

Transfer the ownership of a device

Path variables

id
string GUID required

The device (identifier) to be transferred

Example:
97663bf8-7fb8-10b5-9387-47cd0ff2558c

Notes

CORE BEHAVIOR

Ownership transfer can be between an organisation to a contact, or between two contacts

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
origin_entity
string required

The entity that will transfer the ownership of the device

Enumeration:
ORGANISATION
CONTACT
origin_id
string GUID required

Defines the entity (identifier) that such device’s ownership will be transferred from

Example:
d60ddb7a-31fd-d521-fa57-fc2a3624b462
destination_id
string GUID required

Defines the entity (identifier) that such device’s ownership will be transferred to, usually the destination is a Contact

Example:
4c6d275c-3e97-1bf1-62c6-2d27610e20f0

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The device identifier

Example:
97663bf8-7fb8-10b5-9387-47cd0ff2558c
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/devices/6A24D2B5E44F44B28451FE021FCAD51E/ownership_transfer HTTP/1.1 

Content-Type: application/json

{
    "origin_entity": "CONTACT",
    "origin_id": "d63d52b5-b158-0739-fafb-97c4b17392fc",
    "destination_id": "57eb760c-89da-fe56-f486-b6fd087af3a4"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E"
}
Estimates
POST /estimates/allowance
POST /estimates/billing
POST /estimates/invoicing
POST /estimates/order_fulfillment
POST /estimates/orders
POST /estimates/purchases
POST /estimates/service_delivery
Authorise Usage Consumption
POST /estimates/allowance

Returns an estimation on whether a contact is allowed to consume usage allowance and if yes, the remaining one.

Request parameters

include_remaining
boolean optional

Set to True if the remaining usage allowance should also be included in the response. When set to False, the Web API just informs whether usage consumption is authorised or not.

Default:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string required nullable

The contact consuming usage

account_id
string required nullable

The account authorised to consume usage

product_id
string

The usage product identifier

service
Object

The identifier of the service through which usage is consumed. If not specified, then the response will include all termed and one-time services that allow the specified contact to consume usage. In the latter case, one-time services which are expired or fully consumed are not returned. For termed services, only non-cancelled ones are returned

id
string required

The unique identifier of the service

classification
string required
Enumeration:
TERMED_SERVICE
ONE_TIME_SERVICE
organisation_id
string

The organisation at which usage is consumed

cash_amount
number nullable

The consumed usage’s charged amount.

currency_code
string

The charged amount’s currency.

usage_amount
number nullable

The consumed usage’s amount/volume

Responses

200 OK
Body
Object
estimation_id
string

Usage authorisation’s uniue identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
authorised_usage
Array

Authorised usage among all of the contact’s services. In other words, the remaining usage that the contact is still allowed to consume

Object
amount
string

Remaining usage amount among all services that allow consumption

Example:
2.45
product
Object

The usage service that is authorised for consumption

id
string
sku
string
name
string
measurement_unit
Object
id
string
name
string
Example:
Gigabytes
display_name
string
Example:
GB
services
Array

Lis of services that provide usage authorisation

Object
id
string

subscirption service identifier

classification
string
Enumeration:
ONE_TIME_SERVICE
TERMED_SERVICE
product
Object

The service product which is either a termed or a one-time service

id
string
sku
string
name
string
services
Array

List of services that allow consumption of the requested usage service. By default is not returned unless specified in the request

Object
authorise_consumption
boolean

Returned as True if usage can be consumed, i.e. termed/one-time service has remaining allowance. If no usage allowance limits are set, then usage is always authorised.

Example:
true
currency_code
string

The currency code reated to usage cash amount limits

Example:
EUR
service
Object

The one-time/termed service through which usage is consumed

id
string

Unique identifier fo the termed/one-time service

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
classification
string

Determines if the ervice is a Termed or one-time service

Enumeration:
ONE_TIME_SERVICE
TERMED_SERVICE
Example:
ONE_TIME_SERVICE
product
Object

The service’s product

id
string

Product identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
sku
string

Product SKU

Example:
DAY5BG
name
string

Product name

Example:
Daily 5GB NOW
accumulated_allowance
Object

Accumulated usage allowance in cash amounts

cash_amounts
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
products_allowance
Array
Object
item_type
string
Example:
PRODUCT
item_id
string
name
string
remaining_cash
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
remaining_usage
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
measurement_unit
Object
id
string
name
string
display_name
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/allowance HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "",
    "account_id": "",
    "product_id": "",
    "service": {
        "id": "",
        "classification": "TERMED_SERVICE"
    },
    "organisation_id": "",
    "cash_amount": 1,
    "currency_code": "",
    "usage_amount": 1
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "estimation_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "authorised_usage": [
        {
            "amount": "2.45",
            "product": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "measurement_unit": {
                "id": "",
                "name": "Gigabytes",
                "display_name": "GB"
            },
            "services": [
                {
                    "id": "",
                    "classification": "ONE_TIME_SERVICE",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                }
            ]
        }
    ],
    "services": [
        {
            "authorise_consumption": true,
            "currency_code": "EUR",
            "service": {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "classification": "ONE_TIME_SERVICE",
                "product": {
                    "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                    "sku": "DAY5BG",
                    "name": "Daily 5GB NOW"
                }
            },
            "accumulated_allowance": {
                "cash_amounts": {
                    "per_transaction": 9.99,
                    "per_day": 19.99,
                    "per_billing_cycle": 59.99
                }
            },
            "products_allowance": [
                {
                    "item_type": "PRODUCT",
                    "item_id": "",
                    "name": "",
                    "remaining_cash": {
                        "per_transaction": 9.99,
                        "per_day": 19.99,
                        "per_billing_cycle": 59.99
                    },
                    "remaining_usage": {
                        "per_transaction": 9.99,
                        "per_day": 19.99,
                        "per_billing_cycle": 59.99
                    },
                    "measurement_unit": {
                        "id": "",
                        "name": "",
                        "display_name": ""
                    }
                }
            ]
        }
    ]
}
Billing
POST /estimates/billing

Returns an estimation of a customer’s upcoming billing

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string nullable
Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
organisation_id
string nullable
account_id
string nullable
as_of_date
integer
Example:
1234567
upcoming_billing_cycles
integer
Default:
1
Example:
3

Responses

200 OK
Body
Object
billing_estimate
Array
Object
billing_date
integer
Example:
12345678
billed_period
Object
from_date
integer
Example:
12345678
to_date
integer
Example:
12345678
account
Object
id
string
number
string
name
string
totals
Object
total_amount
number
Example:
9.99
tax_amount
number
Example:
1.99
net_amount
number
Example:
1.99
discount_amount
number
Example:
1.99
invoicing
Array
Object
issued_date
integer
Example:
123456789
due_date
integer
Example:
123456789
currency_code
string
Example:
EUR
is_credit
boolean
wallet_funds_amount
number
Example:
5.99
total_net_amount
integer
Example:
1
total_discount_amount
integer
Example:
1
total_discount_incl_tax
integer
Example:
1
total_tax_amount
number
Example:
0.99
total_price
number

Sum of all products’ prices as these are defined in the product catalog

total_amount
number

Total amount of the invoice that will be generated. Includes taxed and disoucnt amounts

Example:
9.99
amount_due
number

The amount that will be due at the time of the estimation

amount_to_collect
number

Amount that the customer needs to pay at the time of the estimation

account_credit
number

Available account funds that can be used to pay off the Invoice. Available when the account is in credit and/or the account has a credit limit. Account funds are calculated as the account’s credit limit minus the amount in credit. for example credit limit is 100 and account credit is 50, then account fund sis returned as 150

Example:
9.99
taxes_breakdown
Array
Object
tax_amount
number
Example:
0.99
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
line_items
Array
Object
quantity
integer
Example:
1
unit_price
number
Example:
9.99
net_amount
number
Example:
9.99
discount_amount
number
Example:
1
sub_total
number
Example:
9.99
pricing
number

The price of the product as this is configured in the product catalog (including tax or not depending on the tax model)

Example:
11.99
period
Object

Termed service’s debited/credited period

from
integer

The date from which the service is invoiced/credited

to
integer

The date until which the service is invoiced/credited

product
Object

Details about the product

id
string GUID

The product identifier

Example:
ba603bdc-f18f-1d4e-dd07-ad6b57c6e565
sku
string

The product SKU

Example:
DEC1234
name
string

The product name

Example:
Decoder
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
discount
Object

Details about the applied discount

discount_amount
number
Example:
0.96
discount_percentage
number
Example:
1.5
discount_incl_tax
number
Example:
0.98
applied_taxes
Array

Details about the applied taxes

Object
tax_amount
number
Example:
0.99
tax_exempt_reason
string
Example:
CONTACT
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
bundle_product
Object

Defines the main product that the line item is component to it (applicable only when the line item is invoiced as a component of another product)

id
string GUID

The product identifier

Example:
31f2e99d-a5cb-21c1-2866-1a1491989893
sku
string

The product sku

Example:
ICL-001
name
string

The product name

Example:
Iced Latte
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/billing HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "",
    "organisation_id": "",
    "account_id": "",
    "as_of_date": 1234567,
    "upcoming_billing_cycles": 3
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "billing_estimate": [
        {
            "billing_date": 12345678,
            "billed_period": {
                "from_date": 12345678,
                "to_date": 12345678
            },
            "account": {
                "id": "",
                "number": "",
                "name": ""
            },
            "totals": {
                "total_amount": 9.99,
                "tax_amount": 1.99,
                "net_amount": 1.99,
                "discount_amount": 1.99
            },
            "invoicing": [
                {
                    "issued_date": 123456789,
                    "due_date": 123456789,
                    "currency_code": "EUR",
                    "is_credit": true,
                    "wallet_funds_amount": 5.99,
                    "total_net_amount": 1,
                    "total_discount_amount": 1,
                    "total_discount_incl_tax": 1,
                    "total_tax_amount": 0.99,
                    "total_price": 1,
                    "total_amount": 9.99,
                    "amount_due": "",
                    "amount_to_collect": 1,
                    "taxes_breakdown": [
                        {
                            "tax_amount": 0.99,
                            "tax_rate": {
                                "id": "",
                                "name": "",
                                "tax_code": "VAT",
                                "percentage": 1
                            }
                        }
                    ],
                    "line_items": [
                        {
                            "quantity": 1,
                            "unit_price": 9.99,
                            "net_amount": 9.99,
                            "discount_amount": 1,
                            "sub_total": 9.99,
                            "pricing": 11.99,
                            "product": {
                                "id": "ba603bdc-f18f-1d4e-dd07-ad6b57c6e565",
                                "sku": "DEC1234",
                                "name": "Decoder",
                                "classification": "TRACEABLE_PHYSICAL_GOOD"
                            },
                            "discount": {
                                "discount_amount": 0.96,
                                "discount_percentage": 1.5,
                                "discount_incl_tax": 0.98
                            },
                            "applied_taxes": [
                                {
                                    "tax_amount": 0.99,
                                    "tax_exempt_reason": "CONTACT",
                                    "tax_rate": {
                                        "id": "",
                                        "name": "",
                                        "tax_code": "VAT",
                                        "percentage": 1
                                    }
                                }
                            ],
                            "bundle_product": {
                                "id": "31f2e99d-a5cb-21c1-2866-1a1491989893",
                                "sku": "ICL-001",
                                "name": "Iced Latte",
                                "classification": "TRACEABLE_PHYSICAL_GOOD"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}
Invoicing
POST /estimates/invoicing

Estimates how a product will be charged in invoices, quotations, billing without generating any invoices etc. Pricing estimation includes the price, all applicable promotions as well as the taxes to be applied.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string GUID nullable

The contact’s unique identifier.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
account_id
string GUID nullable

The account’s unique identifier

Example:
24c0809f-ed91-4b68-b912-5bd6064d901e
supply_method
string
Enumeration:
ON_SITE
DELIVERY
PICK_UP
fulfilled_by
string

The unique idetifier of the organisation from which the customer purchases prducts

line_items
Array required
Min items: 1
Object
product_id
string GUID required

The unique identifier of a product

bundle_product_id
string GUID
quantity
integer required
Default:
1
Example:
1
price
number

The unit price of the product. If specified, then the pricing strategy is not applied.

Example:
9.99
discount_option
string

Required if a discount value is specified.

Enumeration:
AMOUNT
PERCENTAGE
discount_value
number
Example:
1.11
tax_model
string

Required if a price is specified as input

Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
price_term_id
string

Applicable for termed and one-time services

discount
Object
amount
number
type
string
Enumeration:
AMOUNT
PERCENTAGE

Responses

200 OK

The request has succeeded

Body
Object
issued_date
integer
Example:
123456789
due_date
integer
Example:
123456789
currency_code
string
Example:
EUR
is_credit
boolean
wallet_funds_amount
number
Example:
5.99
total_net_amount
integer
Example:
1
total_discount_amount
integer
Example:
1
total_discount_incl_tax
integer
Example:
1
total_tax_amount
number
Example:
0.99
total_price
number

Sum of all products’ prices as these are defined in the product catalog

total_amount
number

Total amount of the invoice that will be generated. Includes taxed and disoucnt amounts

Example:
9.99
amount_due
number

The amount that will be due at the time of the estimation

amount_to_collect
number

Amount that the customer needs to pay at the time of the estimation

account_credit
number

Available account funds that can be used to pay off the Invoice. Available when the account is in credit and/or the account has a credit limit. Account funds are calculated as the account’s credit limit minus the amount in credit. for example credit limit is 100 and account credit is 50, then account fund sis returned as 150

Example:
9.99
taxes_breakdown
Array
Object
tax_amount
number
Example:
0.99
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
line_items
Array
Object
quantity
integer
Example:
1
unit_price
number
Example:
9.99
net_amount
number
Example:
9.99
discount_amount
number
Example:
1
sub_total
number
Example:
9.99
pricing
number

The price of the product as this is configured in the product catalog (including tax or not depending on the tax model)

Example:
11.99
period
Object

Termed service’s debited/credited period

from
integer

The date from which the service is invoiced/credited

to
integer

The date until which the service is invoiced/credited

product
Object

Details about the product

id
string GUID

The product identifier

Example:
ba603bdc-f18f-1d4e-dd07-ad6b57c6e565
sku
string

The product SKU

Example:
DEC1234
name
string

The product name

Example:
Decoder
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
discount
Object

Details about the applied discount

discount_amount
number
Example:
0.96
discount_percentage
number
Example:
1.5
discount_incl_tax
number
Example:
0.98
applied_taxes
Array

Details about the applied taxes

Object
tax_amount
number
Example:
0.99
tax_exempt_reason
string
Example:
CONTACT
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
bundle_product
Object

Defines the main product that the line item is component to it (applicable only when the line item is invoiced as a component of another product)

id
string GUID

The product identifier

Example:
31f2e99d-a5cb-21c1-2866-1a1491989893
sku
string

The product sku

Example:
ICL-001
name
string

The product name

Example:
Iced Latte
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/invoicing HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "account_id": "24c0809f-ed91-4b68-b912-5bd6064d901e",
    "supply_method": "DELIVERY",
    "fulfilled_by": "",
    "line_items": [
        {
            "product_id": "",
            "bundle_product_id": "",
            "quantity": 1,
            "price": 9.99,
            "discount_option": "AMOUNT",
            "discount_value": 1.11,
            "tax_model": "TAX_EXCLUSIVE",
            "price_term_id": ""
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "issued_date": 123456789,
    "due_date": 123456789,
    "currency_code": "EUR",
    "is_credit": true,
    "wallet_funds": 5.99,
    "total_net_amount": 1,
    "total_discount_amount": 1,
    "total_discount_incl_tax": 1,
    "total_tax_amount": 0.99,
    "total_amount": 9.99,
    "taxes_breakdown": [
        {
            "tax_amount": 0.99,
            "tax_rate": {
                "id": "",
                "name": "",
                "tax_code": "VAT",
                "percentage": 1
            }
        }
    ],
    "line_items": [
        {
            "id": "7CD9C84FA60F9FE407140E20F707726A",
            "sku": "",
            "name": "",
            "tax_model": "TAX_INCLUSIVE",
            "pricing_model": "TIERED",
            "currency": "EUR",
            "quantity": 1,
            "unit_price": 9.99,
            "price_incl_tax": 11.99,
            "net_amount": 9.99,
            "discount": {
                "discount_amount": 0.96,
                "discount_percentage": 1.5,
                "discount_incl_tax": 0.98
            },
            "tax_amount": 0.99,
            "sub_total": 9.99,
            "classification": "",
            "applied_taxes": [
                {
                    "tax_amount": 0.99,
                    "tax_exempt_reason": "CONTACT",
                    "tax_rate": {
                        "id": "",
                        "name": "",
                        "tax_code": "VAT",
                        "percentage": 1
                    }
                }
            ]
        }
    ]
}
Order Fulfillment
POST /estimates/order_fulfillment

Preview order fulfillment information

Notes

The following APIs should be called in order to make an order

  1. Order Fulfillment
  2. Orders
  3. Make an Order

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
supply_method
string required

Preview order based on the supply method

Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
is_open
boolean

Preview order only for open venues

Example:
true
postal_code
string

Preview order based on the postal code

Example:
2415
lat_lot
string

Preview order based on the geo-location (lat/long)

Example:
35.157204,33.314151
address_id
string GUID

Preview order based on the customer address

Example:
28441e3e-767a-b6cc-9a59-6d7705de6428
requested_organisation_id
string GUID

Preview order based on a specific organisation as requested by the customer

Example:
4456e728-019c-86e4-3e4f-bb7920e2ef75
requested_delivery_at
Object

Preview order based on the date and time at which the customer requests the ordered items to be delivered/picked-uo (Applicable only for ordering ahead/scheduling an order)

time
integer required

The order ahead time

Example:
30
time_unit
string required

The order ahead time unit

Example:
MINUTES
date
integer epoch required

The order ahead date

Example:
12312323123
queue_id
string GUID

The id of the queue selected

Example:
532652ff-10b2-1f88-914a-df316249ccf0

Responses

200 200

The request has succeeded

Body
application/json
Array
Object
fulfilled_by
Object

Details about the organisation (business/merchant/venues) that will fulfill the order

id
string GUID

The organisation identifier

Example:
3FD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Best Burger Egkomi
phone
string

The organisation phone number

Example:
+6934222321
address
Object

The organisation address

address_line_1
string

The address line 1

Example:
Ilia Papakyriakou 21
address_line_2
string

The address line 2

Example:
7 Stars Tower
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2415
lat
string

The latitude of the location

Example:
35.157115
lon
string

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
parent_organisation
Object

Details about the parent organisation (business/merchant) of the fulfilled by. Not applicable if the fulfilled by organisation is of type business or merchant

id
string GUID

The organisation identifier

Example:
b1607c37-e750-2324-ac49-6591a86f54b8
name
string

The organisation name

Example:
Best Burger
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
opening_hours
Array

Details about the organisation’s working hours

Object
day_of_week
string

The day of the week that the organisation is open

Example:
MONDAY
opens
string

The time that the organisation opens

Example:
09:00
closes
string

The time that the organisation closes

Example:
20:00
operation
string

The opening hours for each organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
ANY
short_term_operations
Array

Details about the organisation’s availability to offer its services

Object
operation
string

The organisation’s operation type

Enumeration:
DELIVERY
PICK_UP
is_closed
boolean

Defines whether the organisation is temporary closed for offering its services

Example:
false
payment_method_types
Array

The payment methods allowed when ordering from the organisation that fulfills the order

Example:
[
    "CASH","CARD"
]
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/order_fulfillment HTTP/1.1 

Content-Type: application/json

{
    "supply_method": "DIRECT_SALE",
    "is_open": true,
    "postal_code": "2415",
    "lat_lot": "35.157204,33.314151",
    "address_id": "28441e3e-767a-b6cc-9a59-6d7705de6428",
    "requested_organisation_id": "4456e728-019c-86e4-3e4f-bb7920e2ef75",
    "requested_delivery_at": {
        "time": 30,
        "time_unit": "MINUTES", 
        "date": 12312323123
    },
    "queue_id": "532652ff-10b2-1f88-914a-df316249ccf0"
}

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "fulfilled_by": { 
            "id": "3FD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Best Burger Egkomi",
            "phone": "+6934222321",
            "address": {
                "address_line_1": "Ilia Papakyriakou 21",
                "address_line_2": "7 Stars Tower",
                "state_province_county": "Egkomi",
                "town_city": "Nicosia",
                "postal_code": "2415",
                "lat": "35.157115",
                "lon": "33.313719",
                "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
            },
            "parent_organisation": {
                "id": "b1607c37-e750-2324-ac49-6591a86f54b8",
                "name": "Best Burger",
                "creatives": [
                    {
                        "id": "CA123456789AQWSXZAQWS1236547896541",
                        "usage_type": "LOGO",
                        "width": 2159,
                        "height": 3075,
                        "format": "jpg",
                        "url": "https://assets.crm.com/image/logo.jpg",
                        "public_id": "crm-com/image",
                        "media": [
                            {
                                "width": 200,
                                "height": 300,
                                "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                            }
                        ]
                    }
                ]
            },
            "opening_hours": [
                {
                    "day_of_week": "MONDAY",
                    "opens": "09:00",
                    "closes": "20:00",
                    "operation": "ANY"
                }
            ],
            "short_term_operations": [
                {
                    "operation": "PICK_UP",
                    "is_closed": "false"
                }
            ],
            "payment_method_types": [
                "CRM_WALLET"
            ],
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "WALLET_IMAGE",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ]
        }
    }
]
Orders
POST /estimates/orders

Preview order information before making an order including fulfillment and invoice estimations

Notes

The following APIs should be called in order to make an order

  1. Order Fulfillment
  2. Orders
  3. Make an Order

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
account_id
string GUID required
Example:
1bd3e4d3-5981-209b-787d-352dcd5389a3
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
fulfilled_by
string GUID nullable
Example:
271671a0-4bb3-9c2e-a9c7-6490dbfe5939
requested_delivery_at
Object
time
integer
Example:
30
time_unit
string
Example:
MINUTES
date
integer epoch
Example:
12312323123
address_id
string GUID

Appicable and required when the supply method is Delivery

Example:
84bfd840-b520-5bde-8f0a-b36937a2fce7
notes
string
queue_id
string GUID

The queue id retrieval for milestone invoice payment plan

Example:
271671a0-4bb3-9c2e-a9c7-6490dbfe5939
use_wallet_funds
boolean
Default:
false
payment_method_type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
line_items
Array
Object
id
string GUID
Example:
7f45ad8a-b164-2a67-eb93-8651c0f1b101
quantity
integer
Example:
1
price
number
Example:
2.99
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
notes
string
price_terms_id
string GUID

Applicable and required for termed and one-time services. Also applicable for tracceable physical goods which are ordered as Rentals.

Example:
905a4a5d-80d4-1e18-4595-d03c2b9546e1
components
Array
Object
id
string GUID
Example:
6e111025-002b-48d7-a675-6d9e48070b8f
quantity
integer
Example:
1
price
number
Example:
0.5
tax_model
string
Example:
TAX_INCLUSIVE
price_terms_id
string

Applicable only when ordering a service bundle

milestones
Array

These milestones will default to the milestones based on the queue type selected - unless they are edited by the user.

Object
status_id
string GUID
Example:
271671a0-4bb3-9c2e-a9c7-6490dbfe5939
percentage
number

This will be either be the value entered by the user or the value based on the queue configuration.

discount
Object

Ad-hoc discount applied including tax

amount
number
type
string
Enumeration:
AMOUNT
PERCENTAGE
pass
Object

Redeemed Promotion pass for a subscription service

code
string

Pass code

Example:
TB68937255
otp
string

Pass associated OTP (roadmapped)

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

Estimation ID. to be used for placing the order. valid for!!!

Example:
905a4a5d-80d4-1e18-4595-d03c2b9546e1
order_estimate
Object
ordering_allowed
boolean

Indicates whether minimum order amount is met and order can proceed with submission.

Example:
true
minimum_amount
number

Defines the minimum order amount as specified in the fulfillment policy of the organisation fulfilling the order.

fulfilled_by
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
estimated_delivery
Object
time_to_deliver
integer
Example:
1
uot
string
Example:
minutes
delivered_at
integer epoch
Example:
12345565
queue_id
string GUID
Example:
b82648cb-e5f4-53b2-26b3-edca38e3e34f
invoice_estimate
Object
issued_date
integer
Example:
123456789
due_date
integer
Example:
123456789
currency_code
string
Example:
EUR
is_credit
boolean
wallet_funds_amount
number
Example:
5.99
total_net_amount
integer
Example:
1
total_discount_amount
integer
Example:
1
total_discount_incl_tax
integer
Example:
1
total_tax_amount
number
Example:
0.99
total_price
number

Sum of all products’ prices as these are defined in the product catalog

total_amount
number

Total amount of the invoice that will be generated. Includes taxed and disoucnt amounts

Example:
9.99
amount_due
number

The amount that will be due at the time of the estimation

amount_to_collect
number

Amount that the customer needs to pay at the time of the estimation

account_credit
number

Available account funds that can be used to pay off the Invoice. Available when the account is in credit and/or the account has a credit limit. Account funds are calculated as the account’s credit limit minus the amount in credit. for example credit limit is 100 and account credit is 50, then account fund sis returned as 150

Example:
9.99
taxes_breakdown
Array
Object
tax_amount
number
Example:
0.99
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
line_items
Array
Object
quantity
integer
Example:
1
unit_price
number
Example:
9.99
net_amount
number
Example:
9.99
discount_amount
number
Example:
1
sub_total
number
Example:
9.99
pricing
number

The price of the product as this is configured in the product catalog (including tax or not depending on the tax model)

Example:
11.99
period
Object

Termed service’s debited/credited period

from
integer

The date from which the service is invoiced/credited

to
integer

The date until which the service is invoiced/credited

product
Object

Details about the product

id
string GUID

The product identifier

Example:
ba603bdc-f18f-1d4e-dd07-ad6b57c6e565
sku
string

The product SKU

Example:
DEC1234
name
string

The product name

Example:
Decoder
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
discount
Object

Details about the applied discount

discount_amount
number
Example:
0.96
discount_percentage
number
Example:
1.5
discount_incl_tax
number
Example:
0.98
applied_taxes
Array

Details about the applied taxes

Object
tax_amount
number
Example:
0.99
tax_exempt_reason
string
Example:
CONTACT
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
bundle_product
Object

Defines the main product that the line item is component to it (applicable only when the line item is invoiced as a component of another product)

id
string GUID

The product identifier

Example:
31f2e99d-a5cb-21c1-2866-1a1491989893
sku
string

The product sku

Example:
ICL-001
name
string

The product name

Example:
Iced Latte
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
service_delivery_estimate
Array

Applicable only when purchasing termed services and/or renting devices

Object
action_allowed
boolean
Example:
true
allowed_execution_on
integer
Example:
12345678
next_billing_date
integer
Example:
1235678
next_payment_date
integer
Example:
12345678
subscription
Object
life_cycle_state
string
Example:
ACTIVE
terms
Object
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
5
day_of_week
string
Example:
MONDAY
services_to_add
Array
Object
life_cycle_state
string
Example:
EFFECTIVE
quantity
integer
Example:
5
product
Object
id
string
sku
string
name
string
classification
string
Example:
TERMED_SERVICE
trial_period
Object
starts_on
integer
Example:
12345678
ends_on
integer
Example:
12345678
components
Array
Object
id
string
Example:
b82648cb-e5f4-53b2-26b3-edca38e3e34f
sku
string
name
string
dependencies
Array
Object
item_type
string
item_id
string
item_name
string
billing_estimate
Object
billing_date
integer
Example:
12345678
billed_period
Object
from_date
integer
Example:
12345678
to_date
integer
Example:
12345678
totals
Object
total_amount
number
Example:
9.99
tax_amount
number
Example:
1.99
net_amount
number
Example:
1.99
discount_amount
number
Example:
1.99
invoice_estimate
Object
issued_date
integer
Example:
123456789
due_date
integer
Example:
123456789
currency_code
string
Example:
EUR
is_credit
boolean
wallet_funds_amount
number
Example:
5.99
total_net_amount
integer
Example:
1
total_discount_amount
integer
Example:
1
total_discount_incl_tax
integer
Example:
1
total_tax_amount
number
Example:
0.99
total_price
number

Sum of all products’ prices as these are defined in the product catalog

total_amount
number

Total amount of the invoice that will be generated. Includes taxed and disoucnt amounts

Example:
9.99
amount_due
number

The amount that will be due at the time of the estimation

amount_to_collect
number

Amount that the customer needs to pay at the time of the estimation

account_credit
number

Available account funds that can be used to pay off the Invoice. Available when the account is in credit and/or the account has a credit limit. Account funds are calculated as the account’s credit limit minus the amount in credit. for example credit limit is 100 and account credit is 50, then account fund sis returned as 150

Example:
9.99
taxes_breakdown
Array
Object
tax_amount
number
Example:
0.99
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
line_items
Array
Object
quantity
integer
Example:
1
unit_price
number
Example:
9.99
net_amount
number
Example:
9.99
discount_amount
number
Example:
1
sub_total
number
Example:
9.99
pricing
number

The price of the product as this is configured in the product catalog (including tax or not depending on the tax model)

Example:
11.99
period
Object

Termed service’s debited/credited period

from
integer

The date from which the service is invoiced/credited

to
integer

The date until which the service is invoiced/credited

product
Object

Details about the product

id
string GUID

The product identifier

Example:
ba603bdc-f18f-1d4e-dd07-ad6b57c6e565
sku
string

The product SKU

Example:
DEC1234
name
string

The product name

Example:
Decoder
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
discount
Object

Details about the applied discount

discount_amount
number
Example:
0.96
discount_percentage
number
Example:
1.5
discount_incl_tax
number
Example:
0.98
applied_taxes
Array

Details about the applied taxes

Object
tax_amount
number
Example:
0.99
tax_exempt_reason
string
Example:
CONTACT
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
bundle_product
Object

Defines the main product that the line item is component to it (applicable only when the line item is invoiced as a component of another product)

id
string GUID

The product identifier

Example:
31f2e99d-a5cb-21c1-2866-1a1491989893
sku
string

The product sku

Example:
ICL-001
name
string

The product name

Example:
Iced Latte
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
milestone_plan_estimate
Array
Object
status
Object
id
string GUID
Example:
b82648cb-e5f4-53b2-26b3-edca38e3e34f
name
string
Example:
new
colour
string
Example:
FADS876
priority
integer
queue_percentage
number
percentage
number

Custom percetage

amount
number

calculated amount based on order quotation amount x by the percentage. If percentage = null then this amount = order quotation amount x queue percentage.

invalid_products
Array

List of ordered items which were included in the order but cannot be delivered to the consumer at the time of estimation. Invalid ordered products are excluded from the orders cost estimation.

Object
unavailability_reason
string

Details on why the product is considered as invalid and cannot be included in the Order

Enumeration:
VALIDITY_PERIOD

The prodcut’s validity period has expired, i.e. the business is no longer selling this product

AVAILABILITY

The product is temporarily un-available for sale at/by the requested organisation e.g. is out of stock

ORDER_CATALOGUE

The product is not included in an valid/effective Order Catalogue.

product
Object

Product included in the request’s ordered items

id
string

Product identifier

Example:
b82648cb-e5f4-53b2-26b3-edca38e3e34f
sku
string

Product SKU

Example:
PIE
name
string

Product name

Example:
Cheese pie
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/orders HTTP/1.1 

Content-Type: application/json

{
    "account_id": "1bd3e4d3-5981-209b-787d-352dcd5389a3",
    "supply_method": "DELIVERY",
    "fulfilled_by": "271671a0-4bb3-9c2e-a9c7-6490dbfe5939",
    "requested_delivery_at": {
        "time": 30,
        "time_unit": "MINUTES",
        "date": 12312323123
    },
    "address_id": "84bfd840-b520-5bde-8f0a-b36937a2fce7",
    "notes": "",
    "queue_id": "271671a0-4bb3-9c2e-a9c7-6490dbfe5939",
    "use_wallet_funds": "false",
    "payment_method_type": "WALLET",
    "line_items": [
        {
            "id": "7f45ad8a-b164-2a67-eb93-8651c0f1b101",
            "quantity": 1,
            "price": 2.99,
            "tax_model": "TAX_INCLUSIVE",
            "notes": "",
            "price_terms_id": "905a4a5d-80d4-1e18-4595-d03c2b9546e1",
            "components": [
                {
                    "id": "6e111025-002b-48d7-a675-6d9e48070b8f",
                    "quantity": 1,
                    "price": 0.5,
                    "tax_model": "TAX_INCLUSIVE",
                    "price_terms_id": ""
                }
            ]
        }
    ],
    "milestones": [
        {
            "status_id": "271671a0-4bb3-9c2e-a9c7-6490dbfe5939",
            "percentage": 1
        }
    ],
    "discount": {
        "amount": 1,
        "type": "PERCENTAGE"
    },
    "pass": {
        "code": "TB68937255",
        "otp": ""
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "905a4a5d-80d4-1e18-4595-d03c2b9546e1",
    "order_estimate": { 
        "ordering_allowed": "true",
        "minimum_amount": 1,
        "fulfilled_by": {
            "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
            "name": "Bravo Coffee"
        },
        "estimated_delivery": {
            "time_to_deliver": 1,
            "uot": "minutes",
            "delivered_at": 12345565
        },
        "queue_id": "b82648cb-e5f4-53b2-26b3-edca38e3e34f"
    },
    "invoice_estimate": {
        "issued_date": 123456789,
        "due_date": 123456789,
        "currency_code": "EUR",
        "is_credit": true,
        "wallet_funds_amount": 5.99,
        "total_net_amount": 1,
        "total_discount_amount": 1,
        "total_discount_incl_tax": 1,
        "total_tax_amount": 0.99,
        "total_price": 1,
        "total_amount": 9.99,
        "amount_due": 1,
        "amount_to_collect": 1,
        "account_credit": 9.99,
        "taxes_breakdown": [
            {
                "tax_amount": 0.99,
                "tax_rate": {
                    "id": "",
                    "name": "",
                    "tax_code": "VAT",
                    "percentage": 1
                }
            }
        ],
        "line_items": [
            {
                "quantity": 1,
                "unit_price": 9.99,
                "net_amount": 9.99,
                "discount_amount": 1,
                "sub_total": 9.99,
                "pricing": 11.99,
                "product": {
                    "id": "ba603bdc-f18f-1d4e-dd07-ad6b57c6e565",
                    "sku": "DEC1234",
                    "name": "Decoder",
                    "classification": "TRACEABLE_PHYSICAL_GOOD"
                },
                "discount": {
                    "discount_amount": 0.96,
                    "discount_percentage": 1.5,
                    "discount_incl_tax": 0.98
                },
                "applied_taxes": [
                    {
                        "tax_amount": 0.99,
                        "tax_exempt_reason": "CONTACT",
                        "tax_rate": {
                            "id": "",
                            "name": "",
                            "tax_code": "VAT",
                            "percentage": 1
                        }
                    }
                ],
                "bundle_product": {
                    "id": "31f2e99d-a5cb-21c1-2866-1a1491989893",
                    "sku": "ICL-001",
                    "name": "Iced Latte",
                    "classification": "TRACEABLE_PHYSICAL_GOOD"
                }
            }
        ]
    },
    "service_delivery_estimate": [
        {
            "action_allowed": true,
            "allowed_execution_on": 12345678,
            "next_billing_date": 1235678,
            "next_payment_date": 12345678,
            "subscription": {
                "life_cycle_state": "ACTIVE",
                "terms": {
                    "billing_period": {
                        "duration": 1,
                        "uot": "MONTHS"
                    },
                    "billing_day": {
                        "day_of_month": 5,
                        "day_of_week": "MONDAY"
                    }
                }
            },
            "services_to_add": [
                {
                    "life_cycle_state": "EFFECTIVE",
                    "quantity": 5,
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": "",
                        "classification": "TERMED_SERVICE"
                    },
                    "trial_period": {
                        "starts_on": 12345678,
                        "ends_on": 12345678
                    },
                    "components": [
                        {
                            "id": "b82648cb-e5f4-53b2-26b3-edca38e3e34f",
                            "sku": "",
                            "name": ""
                        }
                    ],
                    "dependencies": [
                        {
                            "item_type": "",
                            "item_id": "",
                            "item_name": ""
                        }
                    ]
                }
            ],
            "billing_estimate": {
                "billing_date": 12345678,
                "billed_period": {
                    "from_date": 12345678,
                    "to_date": 12345678
                },
                "totals": {
                    "total_amount": 9.99,
                    "tax_amount": 1.99,
                    "net_amount": 1.99,
                    "discount_amount": 1.99
                },
                "invoice_estimate": {
                    "issued_date": 123456789,
                    "due_date": 123456789,
                    "currency_code": "EUR",
                    "is_credit": true,
                    "wallet_funds_amount": 5.99,
                    "total_net_amount": 1,
                    "total_discount_amount": 1,
                    "total_discount_incl_tax": 1,
                    "total_tax_amount": 0.99,
                    "total_price": 1,
                    "total_amount": 9.99,
                    "amount_due": 1,
                    "amount_to_collect": 1,
                    "account_credit": 9.99,
                    "taxes_breakdown": [
                        {
                            "tax_amount": 0.99,
                            "tax_rate": {
                                "id": "",
                                "name": "",
                                "tax_code": "VAT",
                                "percentage": 1
                            }
                        }
                    ],
                    "line_items": [
                        {
                            "quantity": 1,
                            "unit_price": 9.99,
                            "net_amount": 9.99,
                            "discount_amount": 1,
                            "sub_total": 9.99,
                            "pricing": 11.99,
                            "product": {
                                "id": "ba603bdc-f18f-1d4e-dd07-ad6b57c6e565",
                                "sku": "DEC1234",
                                "name": "Decoder",
                                "classification": "TRACEABLE_PHYSICAL_GOOD"
                            },
                            "discount": {
                                "discount_amount": 0.96,
                                "discount_percentage": 1.5,
                                "discount_incl_tax": 0.98
                            },
                            "applied_taxes": [
                                {
                                    "tax_amount": 0.99,
                                    "tax_exempt_reason": "CONTACT",
                                    "tax_rate": {
                                        "id": "",
                                        "name": "",
                                        "tax_code": "VAT",
                                        "percentage": 1
                                    }
                                }
                            ],
                            "bundle_product": {
                                "id": "31f2e99d-a5cb-21c1-2866-1a1491989893",
                                "sku": "ICL-001",
                                "name": "Iced Latte",
                                "classification": "TRACEABLE_PHYSICAL_GOOD"
                            }
                        }
                    ]
                }
            }
        }
    ],
    "milestone_plan_estimate": [
        {
            "status": {
                "id": "b82648cb-e5f4-53b2-26b3-edca38e3e34f",
                "name": "new",
                "colour": "FADS876",
                "priority": 1
            },
            "queue_percentage": 1,
            "percentage": 1,
            "amount": 1
        }
    ],
    "invalid_products": [
        {
            "unavailability_reason": "VALIDITY_PERIOD",
            "product": {
                "id": "b82648cb-e5f4-53b2-26b3-edca38e3e34f",
                "sku": "PIE",
                "name": "Cheese pie"
            }
        }
    ]
}
Purchases
POST /estimates/purchases

Preview purchase information (including awards and spends) before submitting a purchase customer event

Notes

PURCHASE ESTIMATES FLOW

Integrating purchase estimates in a “submit purchase” flow the following APIs should be called

  1. POST /estimates/purchases
  2. POST /purchases by providing the estimates identifier as return from previous API call

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

application/json
Object
contact
Object required

Defines the contact for whom the purchase is created for (customer identification can be made either using contact id, contact code, cim, contact_token or contact masked card)

id
string GUID required nullable

The contact identifier

Example:
ff67c281-d408-5a10-494a-0bf5e4a86059
code
string required nullable

The contact code

Example:
CO12345
cim
string required nullable

The contact cim

Example:
93002149
contact_token
string required nullable

The contact token

Example:
447212
mask_card
Object nullable
last4
string required nullable

The card’s last 4 digits

Example:
4242
expiration_month
integer required nullable

The card’s expiration month

Example:
10
expiration_year
integer required nullable

The card’s expiration year

Example:
2021
card_owner
Object required nullable

Details about the card owner

surname
string required nullable

The card’s owner surname

Example:
doe
products
Array required nullable

The purchased products. Applicable and required when total transaction is not specified

Object
product_sku
string required nullable

The purchased product sku (product sku and product family are semi-optional)

Example:
FREDESPR001
product_name
string nullable

The purchased product name

Example:
Freddo Espresso
product_family
string required nullable

The purchased product family (product sku and product family are semi-optional)

Example:
Chocolates
net_amount
number required

The purchased product net amount

Example:
14.15
tax_amount
number required

The purchased product vat amount

Example:
1.04
total_amount
number required

The purchased product total amount (net and vat amount)

Example:
15.19
quantity
integer nullable

The purchased quantity

Default:
1
Example:
2
total_transaction
Object required nullable

Applicable when products (sku/family) are not provided

net_amount
number required

The purchase net amount

Example:
1.01
tax_amount
number required

The purchase tax amount

Example:
1.1
total_amount
number required

The purchase total amount (net + tax - discount)

Example:
2.21
discount_amount
number nullable

The discount of the purchase

Example:
1.99
merchant_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
outlet_tap
Object required nullable

The transaction acquiring point that the event was submitted from (id or code must be specified). TAP and Organisation (id) attributes are semi-optional

id
string GUID required nullable

The transaction acquiring point identifier

Example:
4c01d5e4-02c9-ae89-4a3c-eaeb3174fcf0
code
string required nullable

The transaction acquiring point code

Example:
TAP001
organisation_id
string GUID required nullable

The organisation that the purchase was submitted from. Merchant/Venue TAP and Organisation (id) are semi-optional

Example:
9508cbb6-5b6f-e51c-6185-096a629c00e5
classification
Object nullable

The purchase classification

id
string GUID required nullable

The customer event classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string required nullable

The customer event classification name

Example:
Delivery Purchase
pass
Object nullable

Details about the pass

type
string

Pass type

Enumeration:
PROMOTION
GIFT
TOP_UP
Default:
PROMOTION
code
string required

The pass code. For Promotion passes - a Promotion pass will be generated and redeemed as part of the process, the contact_id should also be provided

Example:
SI8276333
pin
string

The pass assocaited pin (if applicable) should be set here for validation

  • If validation is successful, the Purchase Event will be created and wallet funds will be consumed
  • If validation is unsuccessful, the Purchase Event won’t be created and wallet funds won’t be consumed
Example:
1234
otp
string nullable

The pass one time password (if applicable) - not implemented yet for passes

Example:
445729
disable_spends
boolean nullable

Defines whether spend resolution should be disabled or not (if disable spend requests, including instant spends, will not be taken into consideration)

Default:
false
Example:
false
performed_on
integer epoch nullable

The date/time that purchase will be submitted

Example:
1622863554
spend_request
Object nullable

Information related with the spend request that should be created as part of the purchase

amount
number required nullable

The amount to be spent by the specified spend request in system currency

Example:
2.12
restrict_fully_covered
boolean nullable

Defines whether the purchase will be posted successfully only if requested spend amount is fully covered by the available wallet balance - applicable only for Front-End Reduction purchases and only when requested spend amount is specified

Example:
true

Responses

200 200

The request has succeeded

Body
application/json
Object
id
string GUID

The purchase estimates identifier (can be used on post purchase instead of re-submitting the whole purchase attributes)

Example:
cec7736c-75ba-93a0-56f5-6171ae8d4f02
rewards
Object

Details about the estimated awards/spends from this purchase

total_award
number

The estimated total award amount

Example:
1.99
total_spend
number

The sum of all estimated spends (instant discount, auto spends, spends on request)

Example:
2.85
instant_discount
number

The estimated spend amount related to instant discount

Example:
2.01
auto_spend
number

The estimated spend amount related to automatic spend

Example:
0
spend_on_request
number

The estimated spend amount that can be actually spend (related to contact’s spend request)

Example:
0.84
total_open_spend
number

The wallet’s open balance amount that was spent

Example:
2.84
total_commerce_spend
number

The wallet’s commerce balance amount that was spent

Example:
0.01
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/purchases HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "contact": {
        "id": "84b5deb0-48fb-3a34-6d3d-8e8512a33f1d"
    },
    "products": [
        {
            "product_sku": "FREDESPR001",
            "product_name": "Freddo Espresso",
            "net_amount": 14.15,
            "tax_amount": 1.04,
            "total_amount": 15.19,
            "quantity": 2
        }
    ],
    "discount_amount": 1.99,
    "spend_request": {
        "amount": 2.12
    },
    "merchant_tap": {
        "code": "TAP001"
    },
    "outlet_tap": {
        "id": "CEEE83D6E0804A30966F684B0269AD91",
        "code": "TAP002"
    },
    "classification": {
        "name": "Delivery Purchase"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42c48837-7f19-6bfd-3789-7fd672c556c7",
    "rewards": {
        "total_award": 1.99,
        "total_spend": 2.85,
        "instant_discount": 2.01,
        "auto_spend": 1,
        "spend_on_request": 0.84,
        "total_open_spend": 2.84,
        "total_commerce_spend": 0.01
    }
}
Service Delivery
POST /estimates/service_delivery

Returns an estimation of a change perfromed on a subscription service, without making the change. The estimation is based on existing services owned by the customer plus any requested changes.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required
Example:
CHANGE_TERMS
contact_id
string nullable
organisation_id
string nullable
account_id
string required
subscription_id
string
scheduled_date
integer
Example:
12345678
number_of_days
integer
Example:
3
subscription_term_changes
Object
billing_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
MONDAY
payment_method_id
string
funding_source
string
Enumeration:
WALLET
ACCOUNT
services_to_add
Array
Object
product_id
string
price_terms_id
string
quantity
integer
components
Array
Object
product_id
string
price_terms_id
string
services_to_remove
Array
Object
id
string
services_to_change
Array
Object
from_service_id
string
to_service_product_id
string
to_price_terms_id
string
components
Array
Object
product_id
string
price_terms_id
string
service_term_changes
Array
Object
service_id
string
auto_renewal_preference
string
Example:
OPT_IN, OPT_OUT
contract_preference
string
Example:
RENEW, EXTEND
extend_by
Object
period
integer
Example:
3
uot
string
Example:
DAYS
quantity
integer
component_changes
Object

Applicable when amending a flexible service bundle. At least one components should be specifid as either to be added or removed

id
string required

The unique identifier of the service

to_be_added
Array nullable
Unique items: YES
Object
product_id
string
price_terms_id
string
to_be_removed
Array nullable
Unique items: YES
Object
id
string

The service components to be removed

Responses

200 OK
Body
Object
service_delivery_estimate
Array
Object
action_allowed
boolean
Example:
true
allowed_execution_on
integer
Example:
12345678
next_billing_date
integer
Example:
1235678
next_payment_date
integer
Example:
12345678
subscription
Object
life_cycle_state
string
Example:
ACTIVE
terms
Object
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
5
day_of_week
string
Example:
MONDAY
services_to_add
Array
Object
life_cycle_state
string
Example:
EFFECTIVE
product
Object
id
string
sku
string
name
string
trial_period
Object
starts_on
integer
Example:
12345678
ends_on
integer
Example:
12345678
dependencies
Array
Object
item_type
string
item_id
string
item_name
string
services_to_remove
Array
Object
id
string
life_cycle_state
string
Example:
CANCELLED
product
Object
id
string
sku
string
name
string
services_to_change
Array
Object
id
string
life_cycle_state
string
Example:
SWAPPED
product
Object
id
string
sku
string
name
string
change_to_product
Object
id
string
sku
string
name
string
dependencies
Array
Object
item_type
string
item_id
string
item_name
string
components_change
Object
service
Object
id
string
sku
string
name
string
components_added
Array
Object
id
string
sku
string
name
string
components_removed
Array
Object
id
string
sku
string
name
string
billing_estimate
Object
billing_date
integer
Example:
12345678
billed_period
Object
from_date
integer
Example:
12345678
to_date
integer
Example:
12345678
totals
Object
total_amount
number
Example:
9.99
tax_amount
number
Example:
1.99
net_amount
number
Example:
1.99
discount_amount
number
Example:
1.99
invoicing
Array
Object
issued_date
integer
Example:
123456789
due_date
integer
Example:
123456789
currency_code
string
Example:
EUR
is_credit
boolean
wallet_funds_amount
number
Example:
5.99
total_net_amount
integer
Example:
1
total_discount_amount
integer
Example:
1
total_discount_incl_tax
integer
Example:
1
total_tax_amount
number
Example:
0.99
total_price
number

Sum of all products’ prices as these are defined in the product catalog

total_amount
number

Total amount of the invoice that will be generated. Includes taxed and disoucnt amounts

Example:
9.99
amount_due
number

The amount that will be due at the time of the estimation

amount_to_collect
number

Amount that the customer needs to pay at the time of the estimation

account_credit
number

Available account funds that can be used to pay off the Invoice. Available when the account is in credit and/or the account has a credit limit. Account funds are calculated as the account’s credit limit minus the amount in credit. for example credit limit is 100 and account credit is 50, then account fund sis returned as 150

Example:
9.99
taxes_breakdown
Array
Object
tax_amount
number
Example:
0.99
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
line_items
Array
Object
quantity
integer
Example:
1
unit_price
number
Example:
9.99
net_amount
number
Example:
9.99
discount_amount
number
Example:
1
sub_total
number
Example:
9.99
pricing
number

The price of the product as this is configured in the product catalog (including tax or not depending on the tax model)

Example:
11.99
period
Object

Termed service’s debited/credited period

from
integer

The date from which the service is invoiced/credited

to
integer

The date until which the service is invoiced/credited

product
Object

Details about the product

id
string GUID

The product identifier

Example:
ba603bdc-f18f-1d4e-dd07-ad6b57c6e565
sku
string

The product SKU

Example:
DEC1234
name
string

The product name

Example:
Decoder
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
discount
Object

Details about the applied discount

discount_amount
number
Example:
0.96
discount_percentage
number
Example:
1.5
discount_incl_tax
number
Example:
0.98
applied_taxes
Array

Details about the applied taxes

Object
tax_amount
number
Example:
0.99
tax_exempt_reason
string
Example:
CONTACT
tax_rate
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
bundle_product
Object

Defines the main product that the line item is component to it (applicable only when the line item is invoiced as a component of another product)

id
string GUID

The product identifier

Example:
31f2e99d-a5cb-21c1-2866-1a1491989893
sku
string

The product sku

Example:
ICL-001
name
string

The product name

Example:
Iced Latte
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/estimates/service_delivery HTTP/1.1 

Content-Type: application/json

{
    "action": "CHANGE_TERMS",
    "contact_id": "",
    "organisation_id": "",
    "account_id": "",
    "subscription_id": "",
    "scheduled_date": 12345678,
    "number_of_days": 3,
    "subscription_term_changes": {
        "billing_day": {
            "day_of_month": 1,
            "day_of_week": "MONDAY"
        },
        "payment_method_id": "",
        "funding_source": "WALLET"
    },
    "services_to_add": [
        {
            "product_id": "",
            "price_terms_id": "",
            "quantity": 1,
            "components": [
                {
                    "product_id": "",
                    "price_terms_id": ""
                }
            ]
        }
    ],
    "services_to_remove": [
        {
            "id": ""
        }
    ],
    "services_to_change": [
        {
            "from_service_id": "",
            "to_service_product_id": "",
            "to_price_terms_id": "",
            "components": [
                {
                    "product_id": "",
                    "price_terms_id": ""
                }
            ]
        }
    ],
    "service_term_changes": [
        {
            "service_id": "",
            "auto_renewal_preference": "OPT_IN, OPT_OUT",
            "contract_preference": "RENEW, EXTEND",
            "extend_by": {
                "period": 3,
                "uot": "DAYS"
            },
            "quantity": 1
        }
    ],
    "component_changes": {
        "id": "",
        "to_be_added": [
            {
                "product_id": "",
                "price_terms_id": ""
            }
        ],
        "to_be_removed": [
            {
                "id": ""
            }
        ]
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "service_delivery_estimate": [
        {
            "action_allowed": true,
            "allowed_execution_on": 12345678,
            "next_billing_date": 1235678,
            "next_payment_date": 12345678,
            "subscription": {
                "life_cycle_state": "ACTIVE",
                "terms": {
                    "billing_period": {
                        "duration": 1,
                        "uot": "MONTHS"
                    },
                    "billing_day": {
                        "day_of_month": 5,
                        "day_of_week": "MONDAY"
                    }
                }
            },
            "services_to_add": [
                {
                    "life_cycle_state": "EFFECTIVE",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    },
                    "trial_period": {
                        "starts_on": 12345678,
                        "ends_on": 12345678
                    },
                    "dependencies": [
                        {
                            "item_type": "",
                            "item_id": "",
                            "item_name": ""
                        }
                    ]
                }
            ],
            "services_to_remove": [
                {
                    "id": "",
                    "life_cycle_state": "CANCELLED",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                }
            ],
            "services_to_change": [
                {
                    "id": "",
                    "life_cycle_state": "SWAPPED",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    },
                    "change_to_product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    },
                    "dependencies": [
                        {
                            "item_type": "",
                            "item_id": "",
                            "item_name": ""
                        }
                    ]
                }
            ],
            "components_change": {
                "service": {
                    "id": "",
                    "sku": "",
                    "name": ""
                },
                "components_added": [
                    {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                ],
                "components_removed": [
                    {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                ]
            },
            "billing_estimate": {
                "billing_date": 12345678,
                "billed_period": {
                    "from_date": 12345678,
                    "to_date": 12345678
                },
                "totals": {
                    "total_amount": 9.99,
                    "tax_amount": 1.99,
                    "net_amount": 1.99,
                    "discount_amount": 1.99
                },
                "invoicing": [
                    {
                        "issued_date": 123456789,
                        "due_date": 123456789,
                        "currency_code": "EUR",
                        "is_credit": true,
                        "wallet_funds_amount": 5.99,
                        "total_net_amount": 1,
                        "total_discount_amount": 1,
                        "total_discount_incl_tax": 1,
                        "total_tax_amount": 0.99,
                        "total_price": 1,
                        "total_amount": 9.99,
                        "amount_due": "",
                        "amount_to_collect": 1,
                        "taxes_breakdown": [
                            {
                                "tax_amount": 0.99,
                                "tax_rate": {
                                    "id": "",
                                    "name": "",
                                    "tax_code": "VAT",
                                    "percentage": 1
                                }
                            }
                        ],
                        "line_items": [
                            {
                                "quantity": 1,
                                "unit_price": 9.99,
                                "net_amount": 9.99,
                                "discount_amount": 1,
                                "sub_total": 9.99,
                                "pricing": 11.99,
                                "product": {
                                    "id": "ba603bdc-f18f-1d4e-dd07-ad6b57c6e565",
                                    "sku": "DEC1234",
                                    "name": "Decoder",
                                    "classification": "TRACEABLE_PHYSICAL_GOOD"
                                },
                                "discount": {
                                    "discount_amount": 0.96,
                                    "discount_percentage": 1.5,
                                    "discount_incl_tax": 0.98
                                },
                                "applied_taxes": [
                                    {
                                        "tax_amount": 0.99,
                                        "tax_exempt_reason": "CONTACT",
                                        "tax_rate": {
                                            "id": "",
                                            "name": "",
                                            "tax_code": "VAT",
                                            "percentage": 1
                                        }
                                    }
                                ],
                                "bundle_product": {
                                    "id": "31f2e99d-a5cb-21c1-2866-1a1491989893",
                                    "sku": "ICL-001",
                                    "name": "Iced Latte",
                                    "classification": "TRACEABLE_PHYSICAL_GOOD"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}
Financials
GET /journals
List Journals
GET /journals

Retrieve all account and wallet journal entries for all contacts, or based on request parameters

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
entity
string optional

Which journals should be retrieved, blank = both Account & Wallet

Enumeration:
ACCOUNT
WALLET
type
string optional

Type of journal entry action, if not specified then all journals are retrieved

Enumeration:
DEBIT
CREDIT
transaction_type
string optional

Type of financial transaction

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
PAYOUT
TOPUP
TRANSFER
PASS_REDEMPTION
AD_HOC_RETURN
SPEND
AWARD
PURCHASE_CANCELLATION
BACKEND_SPEND
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
posted_date
integer epoch optional

Journal entries posted on this date

reference_number
string optional

The reference number of the journal’s related financial or wallet entity

Example:
A09967
amount
number optional

Journal entry amount

Example:
101.55
contact_id
string optional

Unique Contact id for which to retrieve journal entries

Example:
5a4461f7-9479-4249-8687-eb1661be56d7
account_id
string optional

Unique account id to get journal entries

Example:
0d4d2028-caa6-4a06-9c91-aaa0a195838c
wallet_id
string optional

Unique wallet id to get journal entries

Example:
77832a67-51b2-4a4b-8ee4-dc9bd07dbe59
organisation_id
string optional

Organisation id to get journal entries

Example:
238c3a13-f47a-4712-9217-afce60b4615a
currency_code
string optional

if specified, then only journals of the specified currency are returned

number
string optional

Filter based on entity number (e.g. invoice number, credit note number, refund number)

Example:
INV02131212

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

Journal id

Example:
2f4ea11b-12a6-4321-92d1-f4ede511e203
entity
string

Journal entity type

Enumeration:
ACCOUNT
WALLET
type
string

Type of journal entry action

Enumeration:
DEBIT
CREDIT
Example:
CREDIT
posted_date
integer epoch

Journal posted date

Example:
2343342445
account
Object

Contact’s account details

id
string

Unique id of account for which the jounral entry was posted

Example:
MP09E31269B76D7A65ACCE45B2E68DFD
number
string

Unique account number

Example:
964AC123456
wallet
Object

Contact’s wallet details

id
string GUID

Unique wallet id

Example:
DN89331269B76D7A65ACCE45B2E68DFD
code
string

Unique wallet code

Example:
W00123456
entity_id
string GUID

The unique identifier of the journal entity (e.g. invoice_id, top-up_id, transfer_id etc.)

Example:
6bf75c2b-e9d1-43bc-b5db-a7555919bf04
transaction_type
string

The type of the event

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
PAYOUT
TOPUP
TRANSFER
PASS_REDEMPTION
AD_HOC_RETURN
SPEND
AWARD
PURCHASE_CANCELLATION
BACKEND_SPEND
WALLET_FEE
USE_WALLET_FUNDS
ACHIEVEMENT_CANCELLATION
entity_number
string

Entity number, e.g. invoice number, credit note number, refund number

Example:
CN88942
reference_number
string

Can be: a) Reference number - if the transaction is of type payment, invoice, credit note, payment cancellation, refund. OR b) Code - if the transaction is a top-up or a transfer

Example:
A09967
initial_type
string

The initiating type of an AWARD transaction

Enumeration:
PURCHASE

Award is a result of a purchase event

ACHIEVEMENT

Award is a result of a reward achievement offer

contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
amount
number

Transaction amount

Example:
9.99
currency_code
string

Transaction currency code

Example:
EUR
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/journals HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "2f4ea11b-12a6-4321-92d1-f4ede511e203",
            "entity": "WALLET",
            "type": "CREDIT",
            "posted_date": 2343342445,
            "account": {
                "id": "MP09E31269B76D7A65ACCE45B2E68DFD",
                "number": "964AC123456"
            },
            "wallet": {
                "id": "DN89331269B76D7A65ACCE45B2E68DFD",
                "code": "W00123456"
            },
            "entity_id": "6bf75c2b-e9d1-43bc-b5db-a7555919bf04",
            "transaction_type": "PAYOUT",
            "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_code": "EUR"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}

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",
            "entity_number": "CN88942",
            "reference_number": "A09967",
            "initial_type": "PURCHASE",
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "amount": 9.99,
            "currency_code": "EUR"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Invoices
POST /invoices
PUT /invoices/{id}
POST /invoices/{id}/actions
GET /invoices
GET /invoices/{id}
Create Invoice
POST /invoices

Create a new Invoice financial transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string GUID

The account on which the financial transaction will be posted against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
reference_number
string

The reference number of the financial transaction to be created

Example:
123456
due_date
integer epoch

The due date of the financial transaction. The default value is provided based on settings but the user can provide a different one based on configuration.

Example:
1583846865
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
notes
string

Any notes related to the financial transaction

order_id
string

If an invoice is generated through an order the order id will be passed.

Example:
JHDSHJDKSJHSDJH
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
order_invoice_type
Object
order_invoice_type
string

The type of invoice that is generated through ordering.

Enumeration:
MILESTONE
PROGRESS
FINAL
payment_method
Object

Payment method to be used to pay off the invoice

type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
id
string

The contact payment method’s identifier. Applicable only for payment method types Card, Wallet or Account Debit

financial_transaction_lines
Array
Object
product_id
string GUID required

The product’s unique identifier to be included in the financial transaction

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
quantity
integer

The quantity of the product. Defaults to 1

Example:
2
unit_price
number

The price per unit of the product

Example:
10
discount
Object
discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
number

The discount percentage of the line

Example:
20
sub_total
number

The sub total of the financial transaction line

Example:
200
devices
Array

The IDs of the devices to be sold in case of a stockable/traceable product

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the financial transaction

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/invoices HTTP/1.1 

Content-Type: application/json

{
    "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "reference_number": "123456",
    "due_date": 1583846865,
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "order_id": "JHDSHJDKSJHSDJH",
    "life_cycle_state": "POSTED",
    "order_invoice_type": {
        "order_invoice_type": "FINAL"
    },
    "payment_method": {
        "type": "WALLET",
        "id": ""
    },
    "financial_transaction_lines": [
        {
            "product_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "quantity": 2,
            "unit_price": 10,
            "discount": {
                "discount_amount": 20,
                "discount_percentage": 20
            },
            "sub_total": 200,
            "devices": [
                "CAD1E31269B76D7A65ACCE45B2E68DFD"
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Invoice
PUT /invoices/{id}

Update a Draft Invoice financial transaction

Path variables

id
string required

The id of the Invoice to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
due_date
integer epoch

The due date of the financial transaction. The default value is provided based on settings but the user can provide a different one based on configuration.

Example:
1583846865
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
notes
string

Any notes related to the financial transaction

financial_transaction_lines
Array
Object
line_id
string GUID

The unique identifier of an existing line to be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
product_id
string GUID

The unique identifier of the product to be provided on new lines

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
unit_price
number

The price per unit of the product

Example:
10
quantity
number

The quantity of the product

Example:
2
discount
Object
discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
string

The discount percentage of the line

Example:
20
sub_total
number

The sub total of the financial transaction line

Example:
200
devices
Array

The IDs of the devices to be sold in case of a stockable/traceable product

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/invoices/{id} HTTP/1.1 

Content-Type: application/json

{
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "due_date": 1583846865,
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "financial_transaction_lines": [
        {
            "line_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "product_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "unit_price": 10,
            "quantity": 2,
            "discount": {
                "discount_amount": 20,
                "discount_percentage": "20"
            },
            "sub_total": 200,
            "devices": [
                "CAD1E31269B76D7A65ACCE45B2E68DFD"
            ]
        }
    ],
    "life_cycle_state": "DRAFT"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Perform Invoice Actions
POST /invoices/{id}/actions

Perform actions on an existing Invoice

Path variables

id
string GUID required

The unique identification of the invoice that the actions will be performed against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The action to be performed on the Invoice

Enumeration:
POST

Posts a Draft Invoice. Applicable only for Draft Invoices

REJECT

Rejects an Invoice. Applicable only for Draft Invoices.

CREDIT

Issues a credit note based on the specified invoice. Applicable only for Posted Invoices.

notes
string

The invoice notes available to provide any information on the performed action

amount
number

Applicable when Refunding or Crediting the Invoice. The amount must be less than or equal to the Invoice’s total amount. If not specified when performing these actions, then the Invoice is fully Credited/Refunded.

Example:
9.99

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the invoice

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/invoices/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "CREDIT",
    "notes": "",
    "amount": 9.99
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Invoices
GET /invoices

List all the available Invoices

Request parameters

contact_id
string GUID optional

The unique ID of the contact whose Invoices belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
account_id
string GUID optional

The unique ID of the account whose Invoices belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
is_unsettled
boolean optional

If set to true, then only the unsettled Invoices will be retreived

Example:
true
life_cycle_state
string optional

Filter based on the life cycle state

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
search_value
string optional

The value of the search across number and reference number

Example:
123456
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order_id
string optional

Filter based on order

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
number
string

The financial transaction number

Example:
INV0001
reference_number
string

The financial transaction’s reference number

Example:
123456
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
due_date
integer epoch

The due date of the financial transaction

Example:
1583846865
total_net_amount
number 150

The total net amount of the financial transaction

total_discount_amount
number

The total discount amount of the financial tranasction

Example:
1
total_tax_amount
number

Total tax amount

Example:
2.99
total_amount
number 100

The total amount of the financial transaction

overdue_amount
number

The unpaid amount that passed the financial transaction’s due date

Example:
10
unsettled_amount
number 10

The unpaid amount of the financial transaction

currency_code
string

The invoice’s currency code

Example:
EUR
financial_transaction_lines
Array
Object
id
string GUID

The unique ID of the financial transaction line

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
product
Object

The invoiced product

id
string
sku
string
name
string
quantity
integer

The quantity of the product

Example:
2
unit_price
number

The price per unit of the product

Example:
10
net_amount
number

The net amount

Example:
10
discount
Object
discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
number

The discount percentage of the line

Example:
10
discount_incl_tax
number
tax_amount
number

Total taxed amount for the product

Example:
5
sub_total
number

The sub total of the financial transaction line

Example:
200
applied_taxes
Array

A set of applied tax rates

Object
tax_rate
Object

The applied tax rate

id
string GUID

The identifier of the tax rate

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the tax rate

Example:
Standard VAT
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The tax rate % that was applied

tax_amount
number

The ax amount applied because of the tax rate

Example:
0.2
tax_exempt_reason
string
Enumeration:
CONTACT
PRODUCT
devices
Array

The devices that were sold through this invoice

Object
id
string GUID

The ID of the device

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
serial_number
string

The serial number of the device

Example:
STB123456
taxes_breakdown
Array

A list of taxes that were applied across all lines.

Object
tax_rate
Object
id
string GUID

The unique ID of the tax rate

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the tax rate

Example:
Domestic
tax_code
string

The code of the tax rate

Example:
VAT
percentage
number

The applied tax rate’s percentage that was valid on the date on wich the rate was applied

Example:
20
tax_amount
number

The applied tax amount because of this tax rate

Example:
7.29
notes
string

Any notes of the financial transaction

Example:
December Invoice
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
status
Object

The details pertainign to the status of when the invoice has been released.

id
string
name
string
colour
string
credit_note
Object

The cedit note that was issued in order to refund the invoice.

id
string

The unique identifier of the Credit Note

number
string

The number of the Credit Note

ref_number
string

The reference number of the Credit Note

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/invoices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "number": "INV0001",
            "reference_number": "123456",
            "type": {
                "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
                "name": "Internal Transaction"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "account": {
                "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
                "name": "ACR1234 John Doe",
                "number": "AC123456"
            },
            "life_cycle_state": "PENDING",
            "issued_date": 1583846865,
            "posted_date": 1583846865,
            "due_date": 1583846865,
            "total_net_amount": 1,
            "total_discount_amount": 1,
            "total_tax_amount": 2.99,
            "total_amount": 1,
            "overdue_amount": 10,
            "unsettled_amount": 1,
            "currency_code": "EUR",
            "financial_transaction_lines": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    },
                    "quantity": 2,
                    "unit_price": 10,
                    "net_amount": 10,
                    "discount": {
                        "discount_amount": 20,
                        "discount_percentage": 10,
                        "discount_incl_tax": 1
                    },
                    "tax_amount": 5,
                    "sub_total": 200,
                    "applied_taxes": [
                        {
                            "tax_rate": {
                                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                                "name": "Standard VAT",
                                "tax_code": "VAT",
                                "percentage": 1
                            },
                            "tax_amount": 0.2,
                            "tax_exempt_reason": "PRODUCT"
                        }
                    ],
                    "devices": [
                        {
                            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                            "serial_number": "STB123456"
                        }
                    ]
                }
            ],
            "taxes_breakdown": [
                {
                    "tax_rate": {
                        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                        "name": "Domestic",
                        "tax_code": "VAT",
                        "percentage": 20
                    },
                    "tax_amount": 7.29
                }
            ],
            "notes": "December Invoice",
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "status": {
                "id": "",
                "name": "",
                "colour": ""
            },
            "credit_note": {
                "id": "",
                "number": "",
                "ref_number": ""
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Invoice
GET /invoices/{id}

Get an Invoice

Path variables

id
string required

The id of the Invoice to be retrieved

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
number
string

The financial transaction number

Example:
INV0001
reference_number
string

The financial transaction’s reference number

Example:
123456
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
due_date
integer epoch

The due date of the financial transaction

Example:
1583846865
total_net_amount
number

The total net amount of the financial transaction

Example:
150
total_discount_amount
number

The total discount amount of the financial tranasction

Example:
50
total_tax_amount
number

Total tax amount

Example:
2.99
total_amount
number

The total amount of the financial transaction

Example:
100
overdue_amount
number

The unpaid amount that passed the financial transaction’s due date

Example:
0
unsettled_amount
number

The unpaid amount of the financial transaction

Example:
100
currency_code
string

The invoice’s currency code

Example:
EUR
net_term_days
integer

The account owner’s payment terms based on which the Invoice’s Due date was calculated

notes
string

Any notes of the financial transaction

financial_transaction_lines
Array
Object
id
string GUID

The unique ID of the financial transaction line

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
product
Object

The invoiced product

id
string

The product’s unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
sku
string

The product’s SKU

Example:
abc-12345
name
string

The product’s name

Example:
Decoder
is_stockable
boolean
Example:
true
classification
string
Enumeration:
TERMED_SERVICE
ONE_TIME_SERVICE
USAGE_SERVICE
EXPENSE_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TERMED_SERVICE
quantity
integer

The quantity of the product

Example:
2
unit_price
number

The price per unit of the product

Example:
10
net_amount
number

The net amount

discount
Object

Total discount provided per invoice line

discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
number

The discount percentage of the line

Example:
20
discount_incl_tax
number
tax_amount
number

Total taxed amount for the product

sub_total
number

The sub total of the financial transaction line

Example:
200
period
Object

Invoiced period applicable only when invoicing a termed service.

from
integer

The date from which the service is invoiced

Example:
1651172405
to
integer

The date until which the service is invoiced

Example:
1653764405
applied_taxes
Array

A set of applied tax rates

Object
tax_rate
Object

The applied tax rate

id
string

The identifier of the tax rate

name
string

The name of the tax rate

Example:
Standard VAT
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

Example:
20
tax_amount
number

The ax amount applied because of the tax rate

Example:
0.2
tax_exempt_reason
string
Enumeration:
CONTACT
PRODUCT
applied_discounts
Array

List of discounts applied on the invoice line.

Object
amount
number

The deducted amount

Example:
0.55
type
string

Defines whether the discont was applied on an ad hoc basis or because of a promotion

Enumeration:
AD_HOC
PROMOTION
Example:
PROMOTION
promotion
Object

The applied promotion. Applicable when the discount was applied because of a promotion

id
string

The unique identifier of the promotion

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The promotion’s name

Example:
Xmas -30%
devices
Array

The devices that were sold through this invoice

Object
id
string GUID

The ID of the device

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
serial_number
string

The serial number of the device

Example:
STB123456
taxes_breakdown
Array

A list of taxes that were applied across all lines.

Object
tax_rate
Object
id
string
name
string
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
SALES_TAX
OTHER
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

tax_amount
number

The applied tax amount because of this tax rate

Example:
7.29
credit_note
Object
id
string
number
string
ref_number
string
applied_discounts
Array

List of discounts applied across all invoice lines

Object
amount
string

Total discounted amount

Example:
1.55
type
string

Determines if the discOunt was applied on an ad hoc basis or because of a promotion

Enumeration:
AD_HOC
PROMOTION
promotion
Object

Applicable only for discounts applied because of a promotion

id
string

The promotion’s unique identifier

name
string

The promotion’s name

Example:
Xmas -30% sales
billing_address
Object
name
string

The account owner’s name. This is the company name in case of Contacts of Type Company and the full Prson name

Example:
John Smith
first_name
string

First name of the contact

Example:
John
last_name
string

Last name of the contact

Example:
Smith
email
string

The account owner’s email address

Example:
jsmith@emailaddress.com
phone
string

The acocunt’s owner’s phone

Example:
+4477342239991
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
delivery_address
Object
name
string

The account owner’s name. This is the company name in case of Contacts of Type Company and the full Prson name

Example:
John Smith
first_name
string

First name of the contact

Example:
John
last_name
string

Last name of the contact

Example:
Smith
email
string

The account owner’s email address

Example:
jsmith@emailaddress.com
phone
string

The acocunt’s owner’s phone

Example:
+4477342239991
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/invoices/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "number": "INV0001",
    "reference_number": "123456",
    "type": {
        "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
        "name": "Internal Transaction"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    },
    "account": {
        "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
        "name": "ACR1234 John Doe",
        "number": "AC123456"
    },
    "life_cycle_state": "PENDING",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "due_date": 1583846865,
    "total_net_amount": 150,
    "total_discount_amount": 50,
    "total_tax_amount": 2.99,
    "total_amount": 100,
    "overdue_amount": 1,
    "unsettled_amount": 100,
    "currency_code": "EUR",
    "net_term_days": 1,
    "notes": "",
    "financial_transaction_lines": [
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "product": {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "sku": "abc-12345",
                "name": "Decoder",
                "is_stockable": true,
                "classification": "TERMED_SERVICE"
            },
            "quantity": 2,
            "unit_price": 10,
            "net_amount": 1,
            "discount": {
                "discount_amount": 20,
                "discount_percentage": 20,
                "discount_incl_tax": 1
            },
            "tax_amount": 1,
            "sub_total": 200,
            "period": {
                "from": 1651172405,
                "to": 1653764405
            },
            "applied_taxes": [
                {
                    "tax_rate": {
                        "id": "",
                        "name": "Standard VAT",
                        "tax_code": "SALES_TAX",
                        "percentage": 20
                    },
                    "tax_amount": 0.2,
                    "tax_exempt_reason": "CONTACT"
                }
            ],
            "applied_discounts": [
                {
                    "amount": 0.55,
                    "type": "PROMOTION",
                    "promotion": {
                        "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                        "name": "Xmas -30%"
                    }
                }
            ],
            "devices": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "serial_number": "STB123456"
                }
            ]
        }
    ],
    "taxes_breakdown": [
        {
            "tax_rate": {
                "id": "",
                "name": "",
                "tax_code": "TAX_EXEMPT",
                "percentage": 1
            },
            "tax_amount": 7.29
        }
    ],
    "credit_note": {
        "id": "",
        "number": "",
        "ref_number": ""
    },
    "applied_discounts": [
        {
            "amount": "1.55",
            "type": "AD_HOC",
            "promotion": {
                "id": "",
                "name": "Xmas -30% sales"
            }
        }
    ]
}
Credit Notes
POST /credit_notes
PUT /credit_notes/{id}
POST /credit_notes/{id}/actions
GET /credit_notes
GET /credit_notes/{id}
Create Credit Note
POST /credit_notes

Create a new Credit Note financial transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string GUID

The account on which the financial transaction will be posted against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
reference_number
string

The reference number of the financial transaction to be created

Example:
123456
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
notes
string

Any notes related to the financial transaction

order_id
string
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
financial_transaction_lines
Array
Object
product_id
string GUID

The product’s unique identifier to be included in the financial transaction

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
quantity
integer

The quantity of the product

Example:
2
unit_price
number

The price per unit of the product

Example:
10
discount
Object
discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
number

The discount percentage of the line

Example:
20
sub_total
number

The sub total of the financial transaction line

Example:
200
devices
Array

The IDs of the devices to be returned back to the business in case of a stockable/traceable product

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
financial_transactions_credited
Array

The Invoice financial transactions to be credited by this Credit Note

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/credit_notes HTTP/1.1 

Content-Type: application/json

{
    "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "reference_number": "123456",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "life_cycle_state": "DRAFT",
    "financial_transaction_lines": [
        {
            "product_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "quantity": 2,
            "unit_price": 10,
            "discount": {
                "discount_amount": 20,
                "discount_percentage": 20
            },
            "sub_total": 200,
            "devices": [
                "CAD1E31269B76D7A65ACCE45B2E68DFD"
            ]
        }
    ],
    "financial_transactions_credited": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Credit Note
PUT /credit_notes/{id}

Update a Draft Credit Note financial transaction

Path variables

id
string required

The id of the Credit Note to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
notes
string

Any notes related to the financial transaction

life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
financial_transaction_lines
Array
Object
line_id
string GUID

The unique identifier of an existing line to be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
product_id
string GUID

The unique identifier of the product to be provided on new lines

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
unit_price
number

The price per unit of the product

Example:
10
quantity
number

The quantity of the product

Example:
2
discount
Object
discount_amount
number

The discount amount of the line

Example:
20
discount_percentage
string

The discount percentage of the line

Example:
20
sub_total
number

The sub total of the financial transaction line

Example:
200
devices
Array

The IDs of the devices to be returned back to the business in case of a stockable/traceable product

string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
financial_transactions_credited
Array

The Invoice financial transactions to be credited by this Credit Note

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/credit_notes/{id} HTTP/1.1 

Content-Type: application/json

{
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "life_cycle_state": "DRAFT",
    "financial_transaction_lines": [
        {
            "line_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "product_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "unit_price": 10,
            "quantity": 2,
            "discount": {
                "discount_amount": 20,
                "discount_percentage": "20"
            },
            "sub_total": 200,
            "devices": [
                "CAD1E31269B76D7A65ACCE45B2E68DFD"
            ]
        }
    ],
    "financial_transactions_credited": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Perform Credit Note Actions
POST /credit_notes/{id}/actions

Perform actions on an existing Credit Note

Path variables

id
string GUID required

The unique identification of the credit note that the actions will be performed against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The action to be performed on the Credit Note

Enumeration:
POST
REJECT
notes
string

The credit note notes available to provide any information on the performed action

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the credit note

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/credit_notes/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "REJECT"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Credit Notes
GET /credit_notes

List all the available Credit Notes

Request parameters

contact_id
string GUID optional

The unique ID of the contact whose Credit Notes belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
account_id
string GUID optional

The unique ID of the account whose Credit Notes belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
life_cycle_state
string optional

The life cycle state of the Credit Notes to be retrieved

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
search_value
string optional

The value of the search across number and reference number

Example:
123456
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order_id
string optional

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
number
string

The financial transaction number

Example:
CR0001
reference_number
string

The financial transaction’s reference number

Example:
123456
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
total_net_amount
number

The total net amount of the financial transaction

Example:
150.5
total_discount_amount
number

The total discount amount of the financial tranasction

Example:
50.5
total_tax_amount
number

The total applied tax amount

Example:
1.5
total_amount
number

The total amount of the financial transaction

Example:
100.5
currency_code
string

The credit note’s currency code

Example:
EUR
financial_transaction_lines
Array
Object
id
string GUID

The unique ID of the financial transaction line

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
product_id
Object

The credited product

id
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
sku
string
Example:
PROD0123
name
string
Example:
COFFEE
quantity
integer

The quantity of the product

Example:
2
unit_price
integer

The price per unit of the product

Example:
10
net_amount
number

The net amount of the line

Example:
20.5
discount
Object
discount_amount
number

The discount amount of the line

Example:
20.5
discount_percentage
number

The discount percentage of the line

Example:
20.5
tax_amount
number

Total taxed amount for this product

Example:
1.1
sub_total
number

The sub total of the financial transaction line

Example:
200.5
applied_taxes
Array
Object
tax_rate
Object
id
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string
Example:
DOMESTIC
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

Example:
20
tax_amount
number

The applied tax amount because of the tax rate

Example:
1.5
tax_exempt_reason
string
Enumeration:
CONTACT
PRODUCT
devices
Array

The devices that were returned through this invoice

Object
id
string GUID

The ID of the device

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
serial_number
string

The serial number of the device

Example:
STB123456
taxes_breakdown
Array
Object
tax_rate
Object
id
string GUID
Example:
4AD9C84FA60F9FE407140E20F707726A
name
string
Example:
DOMESTIC TAX
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

Example:
20
tax_amount
number
Example:
1.5
financial_transactions_credited
Array

The financial transactions that are credited by the Credit Note

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
notes
string

Any notes of the financial transaction

organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/credit_notes HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "number": "CR0001",
            "reference_number": "123456",
            "type": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Credit Note"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "account": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "number": "AC123456"
            },
            "life_cycle_state": "DRAFT",
            "issued_date": 1583846865,
            "posted_date": 1583846865,
            "total_net_amount": 150.5,
            "total_discount_amount": 50.5,
            "total_tax_amount": 1.5,
            "total_amount": 100.5,
            "currency_code": "EUR",
            "financial_transaction_lines": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "product_id": {
                        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                        "sku": "PROD0123",
                        "name": "COFFEE"
                    },
                    "quantity": 2,
                    "unit_price": 10,
                    "net_amount": 20.5,
                    "discount": {
                        "discount_amount": 20.5,
                        "discount_percentage": 20.5
                    },
                    "tax_amount": 1.1,
                    "sub_total": 200.5,
                    "applied_taxes": [
                        {
                            "tax_rate": {
                                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                                "name": "DOMESTIC",
                                "tax_code": "TAX_EXEMPT",
                                "percentage": 20
                            },
                            "tax_amount": 1.5,
                            "tax_exempt_reason": "PRODUCT"
                        }
                    ],
                    "devices": [
                        {
                            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                            "serial_number": "STB123456"
                        }
                    ]
                }
            ],
            "taxes_breakdown": [
                {
                    "tax_rate": {
                        "id": "4AD9C84FA60F9FE407140E20F707726A",
                        "name": "DOMESTIC TAX",
                        "tax_code": "TAX_EXEMPT",
                        "percentage": 20
                    },
                    "tax_amount": 1.5
                }
            ],
            "financial_transactions_credited": [
                "CAD1E31269B76D7A65ACCE45B2E68DFD"
            ],
            "notes": ""
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Credit Note
GET /credit_notes/{id}

Get a Credit Note

Path variables

id
string required

The id of the Credit Note to be retrieved

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
number
string

The financial transaction number

Example:
CR0001
reference_number
string

The financial transaction’s reference number

Example:
123456
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
total_net_amount
number

The total net amount of the financial transaction

Example:
150.5
total_discount_amount
number

The total discount amount of the financial tranasction

Example:
50.5
total_tax_amount
number

The total applied tax amount

Example:
1.5
total_amount
number

The total amount of the financial transaction

Example:
100.5
currency_code
string

The credit note’s currency code

Example:
EUR
financial_transaction_lines
Array
Object
id
string GUID

The unique ID of the financial transaction line

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
product
Object

The credited product

id
string

The product’s identifier

sku
string

The product’s SKU

name
string

The product’s name

is_stockable
boolean
classification
string
Enumeration:
TERMED_SERVICE
ONE_TIME_SERVICE
USAGE_SERVICE
EXPENSE_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
quantity
integer

The quantity of the product

Example:
2
unit_price
number

The price per unit of the product

Example:
10
net_amount
number
Example:
20.5
discount
Object
discount_amount
number

The discount amount of the line

Example:
20.5
discount_percentage
number

The discount percentage of the line

Example:
20.5
tax_amount
string

Total taxed amount for this product

sub_total
number

The sub total of the financial transaction line

Example:
200.5
applied_taxes
Array
Object
tax_rate
Object
id
string
name
string
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

tax_amount
number

The applied tax amount because of the tax rate

Example:
1.5
tax_exempt_reason
string
Enumeration:
CONTACT
PRODUCT
devices
Array

The devices that were returned through this invoice

Object
id
string GUID

The ID of the device

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
serial_number
string

The serial number of the device

Example:
STB123456
period
Object

Period credited. Applicable only when crediting termed services

from
integer

The date from which the service is credited

Example:
1651172405
to
integer

The date until which the service is credited

Example:
1653764405
taxes_breakdown
Array
Object
tax_rate
Object
id
string
name
string
tax_code
string
Enumeration:
VAT
TAX_EXEMPT
OTHER
SALES_TAX
percentage
number

The applied tax rate’s percentage that was valid on the date on which the rate was applied

Example:
20
tax_amount
number
Example:
1.5
financial_transactions_credited
Array

The financial transactions that are credited by the Credit Note

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
notes
string

Any notes of the financial transaction

organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/credit_notes/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "number": "CR0001", 
    "reference_number": "123456",
    "type": {
        "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
        "name": "Internal Transaction"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "account": {
        "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
        "name": "ACR1234 John Doe",
        "number": "AC123456"
    },
    "life_cycle_state": "REJECTED",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "total_net_amount": 150.5,
    "total_discount_amount": 50.5,
    "total_tax_amount": 1.5,
    "total_amount": 100.5,
    "currency_code": "EUR",
    "financial_transaction_lines": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "product": {
                "id": "",
                "sku": "",
                "name": "",
                "is_stockable": true,
                "classification": "ONE_TIME_SERVICE"
            },
            "quantity": 2,
            "unit_price": 10,
            "net_amount": 20.5,
            "discount": {
                "discount_amount": 20.5,
                "discount_percentage": 20.5
            },
            "tax_amount": "",
            "sub_total": 200.5,
            "applied_taxes": [
                {
                    "tax_rate": {
                        "id": "",
                        "name": "",
                        "tax_code": "SALES_TAX",
                        "percentage": 1
                    },
                    "tax_amount": 1.5,
                    "tax_exempt_reason": "PRODUCT"
                }
            ],
            "devices": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "serial_number": "STB123456"
                }
            ],
            "period": {
                "from": 1651172405,
                "to": 1653764405
            }
        }
    ],
    "taxes_breakdown": [
        {
            "tax_rate": {
                "id": "",
                "name": "",
                "tax_code": "TAX_EXEMPT",
                "percentage": 20
            },
            "tax_amount": 1.5
        }
    ],
    "financial_transactions_credited": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "notes": "",
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    }
}
Payments
POST /payments
PUT /payments/{id}
POST /payments/{id}/actions
GET /payments
GET /payments/{id}
Create Payment
POST /payments

Create a new Payment financial transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
code
string

Code that uniquely identifies the payment. If not sepcified, then a random and unique 16-digits code will be automatically assigned.

contact_id
string GUID required nullable

The contact on which the financial transaction will be posted against to (contact and organisation are semi-optional)

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
organisation_id
string GUID required nullable

The organisation on which the financial transaction will be posted against to (contact and organisation are semi-optional)

Example:
sfsdfsdf-23-e23-dwe-d-3-dew-dw
type_id
string GUID

The unique identifier of the financial transaction type. Only financial transaction ypes for Payments can be selected. If not specified, then the default Payment financial transaction type will be used.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
amount
number

The amount of the payment

Example:
9.99
currency
string

Defaults to the currency of the customer’s primary account

Example:
EUR
notes
string

Any notes related to the financial transaction

life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
payment_method
string required

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
payment_method_id
string

The contact’s actual preferred payment method. Required and mandatory only for online payments (Card, Wallet and Account Debit).

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
backoffice_code
string

A number that provides a form of identification for the payment. Usually a number that represents the payment in an external system. Can also be used to register the cheque’s number in the corresponding payment method type.

financial_transactions_payable
Array nullable

An array of unique IDs of Invoices to be paid. Either Invoices or External references must be specified (only one of the two)

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
external_transactions_payable
Array nullable

An array of reference numbers of external debits to be paid. Either Invoices or External references must be specified (only one of the two)

string
Example:
INV0123456
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the Payment

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/payments HTTP/1.1 

Content-Type: application/json

{
    "code": "",
    "contact_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "organisation_id": "sfsdfsdf-23-e23-dwe-d-3-dew-dw",
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 9.99,
    "currency": "EUR",
    "notes": "",
    "life_cycle_state": "POSTED",
    "payment_method": "ACCOUNT_DEBIT",
    "payment_method_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "backoffice_code": "",
    "financial_transactions_payable": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "external_transactions_payable": [
        "INV0123456"
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Payment
PUT /payments/{id}

Update an existing draft payment financial transaction

Path variables

id
string required

The id of the Payment to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
amount
number

The amount of the payment

Example:
9.99
notes
string

Any notes related to the financial transaction

payment_method
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
payment_method_id
string

The contact’s actual preferred payment method. Applicable only for online payments (Card, Wallet, Account).

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
financial_transactions_payable
Array nullable

An array of unique IDs of Invoices to be paid. Invoices or External References must be specified (one of the two only)

string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
external_transactions_payable
Array nullable

An array of reference numbers of external debits to be paid. Invoices or External References must be specified (one of the two only)

string
Example:
INV0123456
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the payment

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/payments/{id} HTTP/1.1 

Content-Type: application/json

{
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 9.99,
    "notes": "",
    "payment_method": "CHEQUE",
    "payment_method_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "financial_transactions_payable": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ],
    "external_transactions_payable": [
        "INV0123456"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Perform Payment Actions
POST /payments/{id}/actions

Perform actions on an existing Payment

Path variables

id
string GUID required

The unique identification of the payment that the actions will be performed against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The action to be performed on the Payment

Enumeration:
POST

Posts a Draft Payment

REJECT

Rejects a Draft Payment

REFUND

Refunds a Posted Payment. A Payment can be fully or patially refunded

Example:
POST
payment_cancellation_type_id
string GUID

The id of the cancellation financial transaction type to be created. Applicable only if the action is CANCEL

Example:
4AD9C84FA60F9FE407140E20F707726A
notes
string

The payment notes available to provide any information on the performed action

amount
number

Applicable only when refunding a payment. The refunded amount must be less than or equal to the Payment’s amount. If not specified, then the Payment is fully refunded

Example:
9.99

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the payment

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/payments/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "POST",
    "payment_cancellation_type_id": "4AD9C84FA60F9FE407140E20F707726A",
    "notes": "",
    "amount": 9.99
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Payments
GET /payments

List all available Payments

Request parameters

account_id
string GUID optional

The unique ID of the account whose Payments belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
contact_id
string GUID optional

The unique ID of the contact whose Payments belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
organisation_id
string optional

The unique ID of the organisation whose Payments belong to

life_cycle_state
string optional

The life cycle state of the Payments to be retrieved

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
search_value
string optional

The value of the search across number and reference number

Example:
123456
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string

The unique identifier of the payment

Example:
3DD1E31269B76D7A65ACCE45B2E68DFD
code
string

The payment’s code

Example:
6564443456760009
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150.5
currency
string

The payment’s currency

Example:
EUR
payment_method
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payments?contact_id=4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3DD1E31269B76D7A65ACCE45B2E68DFD",
            "code": "6564443456760009",
            "type": {
                "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
                "name": "Internal Transaction"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "life_cycle_state": "REJECTED",
            "issued_date": 1583846865,
            "posted_date": 1583846865,
            "amount": 150.5,
            "currency": "EUR",
            "payment_method": "ACCOUNT_DEBIT",
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Payment
GET /payments/{id}

Get detailed information of a Payment

Path variables

id
string required

The unique identifier of the to be retrieved

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string

The unique idnetifier of the payment

Example:
2AD1E31269B76D7A65ACCE45B2E68DFD
code
string

The payment’s unique code

Example:
4533340009897776
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150
currency
string

The payment’s currency

payment_method
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
notes
string

Any notes of the financial transaction

payment_method_details
Object

The type of the event

id
string

The unique identifier of the contact’s payment method

identifier
string

A short description of the payment method. Depending on the payment method’s type different informaiton is returned:

  • Card: the brand, followed by the last 4 digits of the card plus expiration month/year
  • Account debit: Name: Bank code followed by the first 5 and the last 9 digits of the account number/IBAN
  • Wallet: Name: Email and/or phone used on registration
Example:
Visa *****1234
financial_transactions_payable
Array

The information of the financial transactions to be paid by the Payment

Object
id
string GUID

The unique ID of the Financial Transaction

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The number of the Financial Transaction

Example:
INV123456
reference_number
string

The reference number of the Financial Transaction

Example:
123456
posted_date
integer epoch

The posted date of the Financial Transaction

Example:
1583846865
due_date
integer epoch

The due date of the Financial Transaction

Example:
1583846865
total_amount
number

The total amount of the financial transaction

Example:
100.5
external_transactions_payable
Array

An array of reference numbers of external debits to be paid.

string
Example:
INV0123456
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payments/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "2AD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "4533340009897776",
    "type": {
        "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
        "name": "Internal Transaction"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "account": {
        "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
        "name": "ACR1234 John Doe",
        "number": "AC123456"
    },
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    },
    "life_cycle_state": "POSTED",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 150,
    "currency": "",
    "payment_method": "ACCOUNT_DEBIT",
    "notes": "",
    "payment_method_details": {
        "id": "",
        "identifier": "Visa *****1234"
    },
    "financial_transactions_payable": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "number": "INV123456",
            "reference_number": "123456",
            "posted_date": 1583846865,
            "due_date": 1583846865,
            "total_amount": 100.5
        }
    ],
    "external_transactions_payable": [
        "INV0123456"
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Payouts
POST /payouts
PUT /payouts/{id}
GET /payuts
GET /payouts/{id}
Create Payout
POST /payouts

Create a new Payout financial transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
code
string

The Payout’s code. If not specified, then a unique and random 16-digit code will be assigned.

Example:
9994440593230796
account_id
string GUID required

The account on which the financial transaction will be posted against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
amount
number required

The amount of the payment

Example:
200
payment_method_type
string required
Enumeration:
CARD
ACCOUNT_DEBIT
CASH
CHEQUE
WALLET
payment_method_id
string

The contact’s payment source to which money will be transferred to as part of the payout. Only Card and Account Debit payment methods can be selected since the payout retrns money back to the customer’s bank account.

type_id
string GUID

The unique identifier of the financial transaction type. If not specified, then the default Payout fianncial trasnaction type will be automatically set.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Automatically set on posting the transaction

Example:
1583846865
notes
string

Any notes related to the financial transaction

issue_reason
string

The reason why the payout was issued

Example:
Refund money

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/payouts HTTP/1.1 

Content-Type: application/json

{
    "code": "9994440593230796",
    "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "amount": 200,
    "payment_method_type": "ACCOUNT_DEBIT",
    "payment_method_id": "",
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "life_cycle_state": "PENDING",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "issue_reason": "Refund money"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Payout
PUT /payouts/{id}

Update a Draft Payout financial transaction

Path variables

id
string required

The id of the Payout to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction.

Example:
1583846865
amount
number

The amount of the payout

Example:
200
notes
string

Any notes related to the financial transaction

life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
payment_method_id
string

The contact’s payment source to which money will be transferred to as part of the payout. Only Card and Account Debit payment methods can be selected since the payout retrns money back to the customer’s bank account.

issue_reason
string

The reason why the refund was created

Example:
Refund Money
payment_method_type
string
Enumeration:
CARD
ACCOUT_DEBIT
WALLET
CASH
CHEQUE

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/payouts/{id} HTTP/1.1 

Content-Type: application/json

{
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 200,
    "notes": "",
    "life_cycle_state": "POSTED",
    "payment_method_id": "",
    "issue_reason": "Refund Money",
    "payment_method_type": "CHEQUE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Payouts
GET /payuts

List all the available Payouts

Request parameters

contact_id
string GUID optional

The unique ID of the contact whose Payouts belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
account_id
string GUID optional

The unique ID of the account whose Refunds belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
life_cycle_state
string optional

The life cycle state of the Refunds to be retrieved

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
search_value
string optional

The value of the search based on the code

Example:
1234
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
code
string

The Payout’s unique and random code

Example:
4545556668909878
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150.5
currency
string

The refund transaction’s currency

Example:
EUR
payment_method_type
string

Indicates the method of refunding the account

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CASH
CHEQUE
payment_method
Object
id
string GUID

The contact’s payment method unique identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
identifier
string

An identifier that briefly describes the contact’s payment method (The last 4 digits for cards, the email for Paypal accounts or the wallet number

Example:
****** 1212
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payuts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "code": "4545556668909878",
            "type": {
                "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
                "name": "Internal Transaction"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "account": {
                "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
                "name": "ACR1234 John Doe",
                "number": "AC123456"
            },
            "life_cycle_state": "REJECTED",
            "issued_date": 1583846865,
            "posted_date": 1583846865,
            "amount": 150.5,
            "currency": "EUR",
            "payment_method_type": "CARD",
            "payment_method": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "identifier": "****** 1212"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Payout
GET /payouts/{id}

Get a Payout

Path variables

id
string required

The id of the financial transaction to be retrieved

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
code
string

The financial transaction code

Example:
44400059654543322
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150.5
currency
string

The refund transaction’s currency

Example:
EUR
payment_method_type
string

Indicates the method of refunding the account

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CASH
CHEQUE
Example:
CARD
payment_method
Object

Payment Method Details

id
string

The contact’s payment method unique identifier

identifier
string

An identifier that briefly describes the contact’s payment method (The last 4 digits for cards, the email for Paypal accounts or the wallet number

Example:
****** 1212
issue_reason
string

The reason why the refund was created

Example:
Refund Money
notes
string

Any notes of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payouts/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "code": "44400059654543322",
    "type": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "Refund"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "account": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "number": "AC123456"
    },
    "life_cycle_state": "REJECTED",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 150.5,
    "currency": "EUR",
    "payment_method_type": "CARD",
    "payment_method": {
        "id": "",
        "name": "",
        "identifier": "****** 1212"
    },
    "issue_reason": "Refund Money",
    "notes": ""
}
Refunds
POST /refunds
PUT /refunds/{id}
POST /refunds/{id}/actions
GET /refunds
GET /refunds/{id}
Create Refund
POST /refunds

Create a new Refund financial transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string required
type_id
string GUID

The unique identifier of the financial transaction id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string
amount
number required

The amount of the payment. If not specified then it defaults to the payments amount. The amount should be less than or equal to the refunded entity’s amount

Example:
9.99
refunded_entity
Object required

The entity based on which the refund will be issued

type
string required

The type of the event

Enumeration:
PAYMENT
INVOICE
PAYMENT_INTENT
Example:
PAYMENT
id
string required

The unique identifier of the refunded entity

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
payment_method
string

Indicates the method of refunding the account

Enumeration:
CASH
CARD
ACCOUNT_DEBIT
CHEQUE
WALLET
payment_method_id
string

The contact’s payment method that will be refunded. If not specifed, then the payment method of the payment will be refunded by default.

issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
notes
string

Any notes related to the financial transaction

issue_reason
string

The reason why the refunds was created

Example:
Refund money
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/refunds HTTP/1.1 

Content-Type: application/json

{
    "account_id": "",
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "code": "",
    "amount": 9.99,
    "refunded_entity": {
        "type": "PAYMENT",
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
    },
    "payment_method": "CASH",
    "payment_method_id": "",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "life_cycle_state": "DRAFT",
    "notes": "",
    "issue_reason": "Refund money",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Refund
PUT /refunds/{id}

Update a Draft Refund financial transaction

Path variables

id
string required

The id of the Refund to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type_id
string GUID

The unique identifier of the financial transaction type id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
amount
number

The amount of the payment

Example:
200
payment_method
string

Indicates the method of refunding the account

Enumeration:
CARD
ACCOUNT_DEBIT
CASH
CHEQUE
WALLET
payment_method_id
string

The payment method of the contact to which the amount will be refnded to.

issued_date
integer epoch

The issued date of the financial transaction. Defaults to current date.

Example:
1583846865
posted_date
integer epoch

The posted date of the financial transaction. Defaults to current date

Example:
1583846865
notes
string

Any notes related to the financial transaction

life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issue_reason
string

The reason why the refund was created

Example:
Refund Money
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/refunds/{id} HTTP/1.1 

Content-Type: application/json

{
    "type_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "amount": 200,
    "payment_method": "WALLET",
    "payment_method_id": "",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "notes": "",
    "life_cycle_state": "REJECTED",
    "issue_reason": "Refund Money",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Perform Refund Actions
POST /refunds/{id}/actions

Perform actions on an existing Refund

Path variables

id
string GUID required

The unique identification of the refund that the actions will be performed against to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The action to be performed on the Refund

Enumeration:
POST
REJECT
notes
string

The refund available to provide any information on the performed action

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the refund

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/refunds/CAD1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "REJECT"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Refunds
GET /refunds

List all the available Refunds

Request parameters

contact_id
string GUID optional

The unique ID of the contact whose Refunds belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
account_id
string GUID optional

The unique ID of the account whose Refunds belong to

Example:
4AD9C84FA60F9FE407140E20F707726A
life_cycle_state
string optional

The life cycle state of the Refunds to be retrieved

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
payment_id
string optional
search_value
string optional

The value of the search using the code

Example:
1234
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
code
string

The financial transaction number

Example:
INV0001
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150.5
currency
string

The refund transaction’s currency

Example:
EUR
payment_method_type
string

Indicates the method of refunding the account

Enumeration:
CARD
ACCOUNT_DEBIT
CASH
CHEQUE
WALLET
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
payment_method
Object
id
string
identifier
string
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/refunds HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "code": "INV0001",
            "type": {
                "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
                "name": "Internal Transaction"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "account": {
                "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
                "name": "ACR1234 John Doe",
                "number": "AC123456"
            },
            "life_cycle_state": "DRAFT",
            "issued_date": 1583846865,
            "posted_date": 1583846865,
            "amount": 150.5,
            "currency": "EUR",
            "payment_method_type": "CASH",
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "payment_method": {
                "id": "",
                "identifier": ""
            },
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Refund
GET /refunds/{id}

Get a Refund

Path variables

id
string required

The id of the financial transaction to be retrieved

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
code
string

The financial transaction code

Example:
44400059654543322
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
account
Object

Details about the related contact’s account

id
string GUID

The account identifier

Example:
8a025412-ec13-550a-4d82-6aef6562ac49
name
string

The account name

Example:
ACR1234 John Doe
number
string

The account unique number

Example:
AC123456
life_cycle_state
string

The life cycle state of the financial transaction

Enumeration:
DRAFT
POSTED
REJECTED
PENDING
issued_date
integer epoch

The date that the financial transaction was issued

Example:
1583846865
posted_date
integer epoch

The date that the financial transaction was posted

Example:
1583846865
amount
number

The amount of the financial transaction

Example:
150.5
currency
string

The refund transaction’s currency

Example:
EUR
payment_method_type
string

Indicates the method of refunding the account

Enumeration:
CARD
ACCOUNT_DEBIT
WALET
CASH
CHEQUE
Example:
CARD
payment_method
Object

Payment Method Details

id
string

The contact’s payment method unique identifier

identifier
string

An identifier that briefly describes the contact’s payment method (The last 4 digits for cards, the email for Paypal accounts or the wallet number

Example:
****** 1212
issue_reason
string

The reason why the refund was created

Example:
Refund Money
notes
string

Any notes of the financial transaction

payment
Object
id
string
code
string
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/refunds/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "code": "44400059654543322",
    "type": {
        "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
        "name": "Internal Transaction"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "account": {
        "id": "8a025412-ec13-550a-4d82-6aef6562ac49",
        "name": "ACR1234 John Doe",
        "number": "AC123456"
    },
    "life_cycle_state": "POSTED",
    "issued_date": 1583846865,
    "posted_date": 1583846865,
    "amount": 150.5,
    "currency": "EUR",
    "payment_method_type": "CARD",
    "payment_method": {
        "id": "",
        "identifier": "****** 1212"
    },
    "issue_reason": "Refund Money",
    "notes": "",
    "payment": {
        "id": "",
        "code": ""
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Integrations
POST /integrations/
PUT /integrations/{id}
DELETE /integrations/{id}
GET /integrations/
GET /integrations/{id}
POST /integrations/{id}/actions
GET /integrations/{id}/logs
Create Integration
POST /integrations/

Creates a new Integration point between CRM.COM and a 3rd party tool

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A name for the new integration

Example:
Basic marketing tool
connector
string required

The 3rd party tool to integrate with

Enumeration:
MIXPANEL
MAILCHIMP
GOOGLE_PLACES
SETTLE
PLUGIN
predefined_plugin_type
string required

Defines the plugin type (release based or custom)

Example:
CUSTOM
integration_type
string required

The implementation’s endpoint

Enumeration:
ADDRESS_REGISTRY
COMMUNICATIONS
MARKETING
PAYMENT_GATEWAYS
POINTS_OF_SALE
PROVISIONING_PROVIDERS
WIFI_PLATFORM
description
string nullable

A description for the integration point

Example:
Utilise marketing tool
enabled
boolean nullable

Defines if integration is enabled or not (defaults to True)

Default:
true
Example:
true
parameters
Array required

A set of parameters required for successfully integrating with the 3rd party tool. At least one is required.

Object
key
string required

The name of the parameter

Example:
API_key
value
string required

The value of the parameter

Example:
abc-123-dfe-22111
label
string required

The parameter’s label

Example:
API Key
type
string required

The parameter’s type

Enumeration:
STRING
NUMBER
INTEGER
is_plugin
boolean required

Defines whether the parameter is plugin related or not

Example:
false
values
Array nullable

Details about an array of mapped values between the internal (CRM) and external (integrator) systems

Object
external_reference
string required

The mapped external reference

Example:
12
value
string required

The mapped value

Example:
725b05ee-cfb3-c950-2db3-562dbbe0fdd4
headers
Array nullable

The (custom) headers that will be used as part of this integration

Object
key
string required

The header key

Example:
api_key
value
string required

The header value

Example:
b436956c-30d2-b1ce-ce98-b90ac2698bd9
authorisation_header
string

Responses

200 OK
Body
Object
id
string GUID

The integration identifier

Example:
e5f0cbc9-e8a0-93cb-bb13-d6f5f20880fa
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/integrations/ HTTP/1.1 

Content-Type: application/json

{
    "name": "Basic marketing tool",
    "connector": "MAILCHIMP",
    "endpoint": "crm.com/marketing",
    "description": "Utilise marketing tool",
    "enabled": "true",
    "parameters": [
        {
            "key": "API_key",
            "value": "abc-123-dfe-22111",
            "label": "API Key",
            "type": "STRING"
        }
    ]
}
Update Integration
PUT /integrations/{id}

Updates an existing integration

Path variables

id
string GUID required

The integration (identifier) that will be updated

Example:
87A08449A8784063814398C104452B27

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The integration name

Example:
Basic marketing tool
description
string nullable

A description for the integration point

Example:
Utilise marketing tool
enabled
boolean required

Defines if integration is enabled or not.

Example:
true
parameters
Array required

A set of parameters required for successfully integrating with the 3rd party tool. At least one is required.

Object
key
string required

The name of the parameter

Example:
API_key
value
string required

The value of the parameter

Example:
abc-123-dfe-22111
label
string required

The parameter’s label

Example:
API Key
type
string required

The parameter’s type

Enumeration:
STRING
NUMBER
INTEGER
is_plugin
boolean required

Defines whether the parameter is plugin related or not

Example:
false
values
Array nullable

Details about an array of mapped values between the internal (CRM) and external (integrator) systems

Object
external_reference
string required

The mapped external reference

Example:
12
value
string required

The mapped value

Example:
725b05ee-cfb3-c950-2db3-562dbbe0fdd4
headers
Array nullable

The (custom) headers that will be used as part of this integration

Object
key
string required

The header key

Example:
api_key
value
string required

The header value

Example:
b436956c-30d2-b1ce-ce98-b90ac2698bd9

Responses

200 OK
Body
Object
id
string GUID

The integration identifier

Example:
87A08449A8784063814398C104452B27
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/integrations/87A08449A8784063814398C104452B27 HTTP/1.1 

Content-Type: application/json

{
    "name": "Basic marketing tool",
    "endpoint": "",
    "description": "Utilise marketing tool",
    "enabled": "true",
    "parameters": [
        {
            "key": "",
            "value": "",
            "label": "",
            "type": "NUMBER"
        }
    ]
}
Delete Integration
DELETE /integrations/{id}

Removes an existing Integration

Path variables

id
string GUID required

The integration (identifier) that will be deleted

Example:
87A08449A8784063814398C104452B27

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/integrations/87A08449A8784063814398C104452B27 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Integrations
GET /integrations/

Retireves a list of configured integration points between CRM.COM and 3rd party tools (enabled or not)

Request parameters

connector
string optional

List integration for specific connector

Enumeration:
MIXPANEL
MAILCHIMP
GOOGLE_PLACES
SETTLE
PLUGIN
integration_type
string optional

Filters based on integration type

Enumeration:
ADDRESS_REGISTRY
COMMUNICATIONS
MARKETING
PAYMENT_GATEWAYS
POINTS_OF_SALE
PROVISIONING_PROVIDERS
WIFI_PLATFORM
service_owner_integrations
boolean optional

If set, retrieve the integrations of the business as usual but if the business does not have configured or enable an integration and its service owner does it returns the integration of the service owner

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The integration identifier

Example:
8b724e8a-26a0-4c70-a959-b87d6acf8b50
name
string

The integration name

Example:
Twinsoft
description
string

The integration description

Example:
Twinsoft POS Integration
connector
string

The integration connector

Example:
TWINSOFT
integration_type
string

The implementation’s endpoint

Enumeration:
ADDRESS_REGISTRY
COMMUNICATIONS
MARKETING
PAYMENT_GATEWAYS
POINTS_OF_SALE
PROVISIONING_PROVIDERS
WIFI_PLATFORM
enabled
boolean

Defines whether the integration is enabled or not

Example:
true
media_url
string

The media URL for the integration logo (applicable only for PLUGIN types)

Example:
crm.com/provider.png
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/integrations/ HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "8b724e8a-26a0-4c70-a959-b87d6acf8b50",
            "name": "Twinsoft",
            "description": "Twinsoft POS Integration",
            "connector": "TWINSOFT",
            "integrationType": "POINTS_OF_SALE",
            "enabled": true
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Integration
GET /integrations/{id}

Retrieve details for a specific integration

Path variables

id
string GUID required

The integration (identifier) for which details will be retrieved

Example:
87A08449A8784063814398C104452B27

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The integration’s identifier

Example:
F8F8E9DA009A4B70BCEEB113B183456D
name
string

The integration’s name

Example:
Marketing tool
description
string

The integration’s description

Example:
Default marketing tool used for forwarding email campaigns
connector
string

The 3rd party tool to integrate with

Enumeration:
MIXPANEL
MAILCHIMP
GOOGLE_PLACES
SETTLE
PLUGIN
integration_type
string

The implementation’s endpoint

Enumeration:
ADDRESS_REGISTRY
COMMUNICATIONS
MARKETING
PAYMENT_GATEWAYS
POINTS_OF_SALE
PROVISIONING_PROVIDERS
WIFI_PLATFORM
enabled
boolean

Defines whether the integration is enabled or not

Example:
true
parameters
Array

A list of parameters required for the integration

Object
key
string

The name of the parameter

Example:
API_Key
value
string

The value of the parameter

Example:
123458449A8784063814398C104452B27
label
string

The parameter’s label

Example:
API Key
type
string

The parameter’s type

Enumeration:
STRING
NUMBER
INTEGER
is_plugin
boolean

Defines whether the parameter is plugin related or not

Example:
true
is_read_only
boolean
Default:
false
Example:
true
values
Array

Details about an array of mapped values between the internal (CRM) and external (integrator) systems

Object
external_reference
string

The mapped CRM external reference

Example:
201f2adb-174e-50d8-d0aa-f431711c8079
value
string

The mapped integrator value

Example:
12
media_url
string

The media URL for the integration logo (applicable only for PLUGIN types)

Example:
crm.com/provider.png
logo_media_url
string

The media (logo) URL for the integration logo (applicable only for PLUGIN types)

Example:
crm.com/logo-provider.png
headers
Array

The (custom) headers that will be used as part of this integration

Object
key
string

The header key

Example:
api_key
value
string

The header value

Example:
b436956c-30d2-b1ce-ce98-b90ac2698bd9
authorisation_header
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/integrations/87A08449A8784063814398C104452B27 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "F8F8E9DA009A4B70BCEEB113B183456D", 
    "name": "Marketing tool",
    "description": "Default marketing tool used for forwarding email campaigns",
    "connector": "SETTLE",
    "integration_type": "PAYMENT_GATEWAYS",
    "enabled": "true",
    "parameters": [
        {
            "key": "API_Key",
            "value": "123458449A8784063814398C104452B27",
            "label": "API Key",
            "type": "STRING",
            "is_plugin": "true",
            "is_read_only": "true",
            "values": [
                {
                    "external_reference": "201f2adb-174e-50d8-d0aa-f431711c8079",
                    "value": "12"
                }
            ]
        }
    ],
    "media_url": "crm.com/provider.png",
    "logo_media_url": "crm.com/logo-provider.png"
}
Perform Integration Actions
POST /integrations/{id}/actions

Updates a single integration based on the preferred action

Path variables

id
string GUID required

The integration (identifier) that a new API Key will be generated

Example:
6346ff58-3691-05c9-513e-f996299a9186

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The action that will be applied on the integration

Enumeration:
API_KEY

Generate a new API Key for the integration

Responses

200 OK
Body
Object
id
string GUID

The integration identifier

Example:
dad569a1-b5c0-eae2-4659-1753df6a8b7f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/integrations/6346ff58-3691-05c9-513e-f996299a9186/actions HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "action": "API_KEY"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "dad569a1-b5c0-eae2-4659-1753df6a8b7f"
}
List Integration Logs
GET /integrations/{id}/logs

Search and retrieve requests sent to an Integrator

Path variables

id
string GUID required

The integration (identifier) of which logs should be retrieved

Example:
2dae3ca9-62aa-2e0a-3029-a6ac9afc47c4

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
state
string optional

Filter based on the request state

Enumeration:
PENDING
SUCCESS
FAILED
contact_id
string GUID optional

Filter based on contact

Example:
7a62e27d-eeb8-1fea-8260-17a72110de51
subscription_id
string GUID optional

Filter based on subscription

Example:
7a62e27d-eeb8-1fea-8260-17a72110de51
submitted_on
string optional
user_id
string GUID optional

Filter based on user

Example:
7a62e27d-eeb8-1fea-8260-17a72110de51

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string GUID

The integration request unique identifier

Example:
90f47a4a-344d-2433-234b-553ce143187e
state
string

The state of the integration request

Enumeration:
PENDING
SUCCESS
FAILED
submitted_on
integer epoch

The date that such request was made

Example:
1596093272
request_code
string

A code that describes the request

body
string

The request body that was sent

Example:
POST /crm.com/delivery HTTP/1.1 Host: staging.crm.com Content-Type: application/json api_key: 123456789012-1234-1234-1234-123456789012 Content-Type: text/plain { "contact_id": "123456789012-ABCD-ABCD-ABCD-123456789012", "amount": 20.45 }
response
string

The response that was sent

Example:
{ "status": { "code": "COM.CRM.EXCEPTION.INVALIDTOKENEXCEPTION", "description": "The specific token is not valid.", "message": "The token is invalid, please obtain a new one." } }
contact
Object

The contact that owns the subscription

id
string GUID

The contact’s identifier

Example:
437f21e8-f2e5-a774-101f-c1a8369d3ab0
name
string

The contact’s name

Example:
John Smith
code
string

The contact’s code

Example:
18235
error_code
string
error_description
string
reference_number
string
user
Object

The user who performed the event

id
string GUID

The unique identifier of the user

Example:
4eac7060-307f-3937-2762-2beed146101f
name
string

The user’s person name

Example:
Jane Smith
email
string

The user’s email address

Example:
jsmith@acompany.com
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/integrations/{id}/logs HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "API1E31269B76D7A65ACCE45B2E68DFD",
            "state": "FAILED",
            "date": 1596093272,
            "request_code": "",
            "body": "POST /crm.com/delivery HTTP/1.1 Host: staging.crm.com Content-Type: application/json api_key: 123456789012-1234-1234-1234-123456789012 Content-Type: text/plain  {     \"contact_id\": \"123456789012-ABCD-ABCD-ABCD-123456789012\",     \"amount\": 20.45 }",
            "response": "{     \"status\": {         \"code\": \"COM.CRM.EXCEPTION.INVALIDTOKENEXCEPTION\",         \"description\": \"The specific token is not valid.\",         \"message\": \"The token is invalid, please obtain a new one.\"     } }",
            "contact": {
                "id": "API1E31269B76D7A65ACCE45B2E68WIH",
                "name": "John Smith",
                "code": "18235"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Mixpanel
GET /cohorts
POST /cohorts/{id}/user_profiles
List Cohorts
GET /cohorts

Returns a list of Cohorts configured in Mixpanel. Any Cohort will then be available to be imported in CRM.COM as a segment

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The cohort identifier

Example:
fb47dde9-7de4-f88f-5430-384ea51ad480
name
string

The cohor name

Example:
Great buyers
description
string

The cohor description

Example:
Customers with moe then £500 purchases during the last month
count
integer

The number of cohors

Example:
159
created_date
integer epoch

The cohor created date

Example:
332222331111
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/cohorts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content":[
        {    
            "id": "", 
            "name": "Great buyers",
            "description": "Customers with moe then £500 purchases during the last month",
            "count": 159,
            "created_date": 332222331111
        }
    ]
}
Import User Profiles
POST /cohorts/{id}/user_profiles

Creates a new segment within CRM.COM that includes all user profiles of a Mixpanel cohort. A single segment can be created per Web API call.

Path variables

id
string GUID required

The Mixpanel Cohort (identifier) whose user profiles will be included in the segment

Example:
aef5b1c2-d407-e018-6563-d5dfa17870fb

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The segment identifier

Example:
87A08449A8784063814398C104452B27
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/cohorts/aef5b1c2-d407-e018-6563-d5dfa17870fb/user_profiles HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "87A08449A8784063814398C104452B27"
}
Mailchimp
POST /lists
Create List
POST /lists

Create a new segment in Mailchimp based on a CRM.COM segment

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
id
string GUID required

The segment’s identifier

Example:
87A08449A8784063814398C104452B27

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/lists HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "id": "87A08449A8784063814398C104452B27"
}

HTTP/1.1 200 OK 
Address Registry
GET /addresses
Address Lookup
GET /addresses

Returns a list of addresses based on the external address registry systems that CRM.COM integrates with

Request parameters

integration
string optional

The address registry that lookup will be performed

Enumeration:
GOOGLE
address
string required

The address that lookup will be performed against (address and latlng are semi-optional)

Example:
The address that lookup will be performed against
latlng
string optional

The lat and lng coordinates that lookup will be performed against (address and latlng are semi-optional)

Example:
40.714224,-73.961452

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array

Information about the retrieved address lookups

Object
address
string

The full address as returned by the address registry

Example:
Elia Papakyriakou, Egkomi, 2415, Nicosia, Cyprus
address_line_1
string

The address information

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the address

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the address

Example:
Egkomi
town_city
string

The town/city of the address

Example:
Nicosia
postal_code
string

The postal code of the address

Example:
2415
country_code
string

The country code of the address

Example:
CY
lan
number

The latitude of the address

Example:
12.98
lon
number

The longitude of the address

Example:
22.98
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ad23rwef2323f23f2f
types
Array

The Google types that will be retrieved

string
Examples:
BakeryAccounting
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/addresses?address=The address that lookup will be performed against HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "address": "Elia Papakyriakou, Egkomi, 2415, Nicosia, Cyprus",
            "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",
            "lan": 12.98,
            "lon": 22.98,
            "googlePlaceId": "ad23rwef2323f23f2f",
            "types": [
                "Accounting"
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "address": "Elia Papakyriakou, Egkomi, 2415, Nicosia, Cyprus",
            "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",
            "lan": 12.98,
            "lon": 22.98,
            "googlePlaceId": "ad23rwef2323f23f2f",
            "types": [
                "Accounting"
            ]
        }
    ]
}
Provisioning Providers
GET /provisioning/ird_commands
POST /provisioning/ird_commands
GET /provisioning/service_commands
POST /provisioning/service_commands
POST /provisioning/utility
Get IRD Commands
GET /provisioning/ird_commands

Retrieve a list of Integrated Receiver/Decoder (IRD) commands (of a device) as implemented in a provisoning adapter. Either the provisioning adapter’s unique identifier must be specified or the external reference (usually the serial number) of the device

Request parameters

integration_id
string optional

The unique identifier of the provisioning provider’s plugin

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
name
string

The name of the command

Example:
Reset PIN
label
string

The label of the command as this wll be displayed in the UI

Example:
Reset Device PIN
code
string

A unique code of the command. Value varies according to the implemented IRD commands per provisioning provider.

Enumeration:
RESET_PIN
REFRESH
description
string

A description of the command that can be used as tooltip in the UI

Example:
Resets the PIN to a given value
metadata_attributes
Array

Lis tof extra information that might be required to be prvided as int when sending the command to the provider

Object
key
string

A unique key

Example:
pin
label
string

The label of the parameter as this will be displaye din the UI

Example:
PIN
description
string

A description of the reuired parameter

Example:
the new pin
field
string

The parameter’s field type used for UI purposes

Enumeration:
SELECTION
TEXT
is_mandatory
boolean

Indicates whether the parameter is mandatory to send the cmmand successfully

Default:
false
Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/provisioning/ird_commands HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "name": "Reset PIN",
            "label": "Reset Device PIN",
            "code": "RESET_PIN",
            "description": "Resets the PIN to a given value",
            "metadata_attributes": [
                {
                    "key": "pin",
                    "label": "PIN",
                    "description": "the new pin",
                    "field": "SELECTION",
                    "is_mandatory": true
                }
            ]
        }
    ]
}
Send IRD command
POST /provisioning/ird_commands

Send an Integrated Receiver/Decoder (IRD) command for a device over to the provisoning adapter. The supported commands as well as detailed information on how to call them such as the required input paramters, can be retrieved from the plugin integration via the GET provisionig/ird_commands Web API.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact
Object

Contact information.

id
string

Unique contatc identifier

Example:
-
code
string

Contact code

Example:
5454666678780009
state
string

The contact’s state on CRM.COm side. This state determines if the contact still has active or inactive or cancelled services once the event is performed.

Enumeration:
ACTIVE
INACTIVE
TERMINATED
Example:
ACTIVE
name
string

Contact full name

Example:
John Smith
subscription
Object

Subscription Information

id
string

Subscription identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
code
string

Subscription code

Example:
5454666678780009
external_reference
string required

The external reference of the device to which the IRD command will be sent such as its serial number

Example:
STB00013929322
code
string required

The IRD command’s unique code as this is implemented by the provisioning plugin

Example:
RESET_PIN
device_location
string nullable

The device’s location. Required only when sending a command related to the device’s physical locatin/region.

Example:
master room
metadata_attributes
Array nullable

A list of extra paramters (apart from the external reference) that are required to successfully send the command. Mandatory input paramters msut be specified, otherwise default values set up in Provisioning Providers configuration will be used

Object
key
string required

The parameter’s key

Example:
pin
value
string required

The parameter’s value

Example:
1234

Responses

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

200 OK

The request has succeeded

Example 1
POST https://sandbox.crm.com/backoffice/v1/provisioning/ird_commands HTTP/1.1 

Content-Type: application/json

{
    "contact": {
        "id": "-",
        "code": "5454666678780009",
        "state": "ACTIVE",
        "name": "John Smith"
    },
    "subscription": {
        "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
        "code": "5454666678780009"
    },
    "external_reference": "STB00013929322",
    "code": "RESET_PIN",
    "device_location": "master room",
    "metadata_attributes": [
        {
            "key": "pin",
            "value": "1234"
        }
    ]
}

HTTP/1.1 200 OK 
Get Service Commands
GET /provisioning/service_commands

Retrieve a list of service commands as implemented in a provisoning adapter. The provisioning adapter’s unique identifier must be specified

Request parameters

integration_id
string optional

The unique identifier of the provisioning provider’s plugin

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
name
string

The name of the command

Example:
Reset Service
label
string

The label of the command as this wll be displayed in the UI

Example:
Reset Service
code
string

A unique code of the command. Value varies according to the implemented IRD commands per provisioning provider.

Enumeration:
RESET_SERVICE
REFRESH
description
string

A description of the command that can be used as tooltip in the UI

Example:
Resets the service
metadata_attributes
Array

List of extra information that might be required to be provided when sending the command to the provider

Object
key
string

A unique key

Example:
pin
label
string

The label of the parameter as this will be displaye din the UI

Example:
PIN
description
string

A description of the reuired parameter

Example:
the new pin
field
string

The parameter’s field type used for UI purposes

Enumeration:
SELECTION
TEXT
is_mandatory
boolean

Indicates whether the parameter is mandatory to send the cmmand successfully

Default:
false
Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/provisioning/service_commands HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "Reset Service",
            "label": "Reset Service",
            "code": "RESET_SERVICE",
            "description": "Resets the service",
            "metadata_attributes": [
                {
                    "key": "pin",
                    "label": "PIN",
                    "description": "the new pin",
                    "field": "TEXT",
                    "is_mandatory": true
                }
            ]
        }
    ]
}
Send Service Command
POST /provisioning/service_commands

Send a command for a service over to the provisioning provider integration. The supported commands as well as detailed information on how to call them such as the required input paramters, can be retrieved from the plugin integration via the GET provisioning/service_commands Web API.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
integration_id
string required

The unique identifier of the provisioning provider integration

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
service_id
string required

The service for which the command will be sent

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
code
string required

The command’s code as this was provided by the integration

Example:
RESET_SERVICE
contact
Object

Contact who subscribed to the service

id
string

Contact identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
code
string

Contact code

Example:
A0111012
name
string

Contatc name

Example:
John Smith
metadata_attributes
Array nullable

A list of extra parameters (apart from the external reference) that are required to successfully send the command. Get Service Commands Web API indicates which are there paramteres and which ones are also mandatory

Object
key
string required

The parameter’s key

Example:
pin
value
string required

The parameter’s value

Example:
1234

Responses

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

200 OK

The request has succeeded

Example 1
POST https://sandbox.crm.com/backoffice/v1/provisioning/service_commands HTTP/1.1 

Content-Type: application/json

{
    "integration_id": "",
    "service_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "code": "RESET_SERVICE",
    "contact": {
        "id": "",
        "code": "A0111012",
        "name": "John Smith"
    },
    "metadata_attributes": [
        {
            "key": "pin",
            "value": "1234"
        }
    ]
}

HTTP/1.1 200 OK 
Provisioning Utility
POST /provisioning/utility

Send an Integrated Receiver/Decoder (IRD) command to a group of devices over to the provisoning adapter. The supported commands as well as detailed information on how to call them such as the required input paramters, can be retrieved from the plugin integration via the GET provisioning/ird_commands Web API.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
external_reference
string required

The external reference of the device to which the IRD command will be sent such as its serial number

Example:
STB00013929322
code
string required

The IRD command’s unique code as this is implemented by the provisioning plugin

Example:
RESET_PIN
metadata_attributes
Array nullable

A list of extra paramters (apart from the external reference) that are required to successfully send the command. Mandatory input paramters msut be specified, otherwise default values set up in Provisioning Providers configuration will be used

Object
key
string required

The parameter’s key

Example:
pin
value
string required

The parameter’s value

Example:
1234
contacts
Array of string nullable

A list of contact unique identifiers. The IRD commad is sent to all devices owned/rented by the specified contacts

Unique items: YES
services
Array of string nullable

A list of service product identifiers. The IRD command will be sent to the devices on whicch at least one of the specified service is enabled on.

Unique items: YES
products
Array of string nullable

A list of physical good products (the product of a device). The IRD command is sent only to devices whose product is one of the specified ones

Unique items: YES
devices
Array of string nullable

A list of devices external references (e.g. device serial number). Only the specified devices will receive the IRD command

Unique items: YES

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/provisioning/ird_commands HTTP/1.1 

Content-Type: application/json

{
    "external_reference": "STB00013929322",
    "code": "RESET_PIN",
    "device_location": "master room",
    "metadata_attributes": [
        {
            "key": "pin",
            "value": "1234"
        }
    ]
}

HTTP/1.1 201 Created 
Payment Gateways
GET /payment_gateways
List Payment Gateways
GET /payment_gateways

Retrieves a list of configured Payment Gateway integration points between CRM.COM (enabled). Only integrations of type Paymet Gateways are retrieved

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The integration identifier

Example:
8b724e8a-26a0-4c70-a959-b87d6acf8b50
name
string

The integration name

Example:
PayPal
description
string

The integration description

Example:
PayPal payment gateway
connector
string

The integration connector

Example:
PLUGIN
integration_type
string

The implementation’s endpoint

Enumeration:
ADDRESS_REGISTRY
COMMUNICATIONS
MARKETING
PAYMENT_GATEWAYS
POINTS_OF_SALE
PROVISIONING_PROVIDERS
WIFI_PLATFORM
enabled
boolean

Defines whether the integration is enabled or not

Example:
true
media_url
string

The media URL for the integration logo (applicable only for PLUGIN types)

Example:
crm.com/provider.png
classifications
Array
string
Enumeration:
PAYMENTS
REFUNDS
PAYOUTS
payment_method_types
Array
string
Enumeration:
CARD
WALLET
ACCOUNT_DEBIT
details
Object

Required paymentmethod details per allowed pament method type

account_debit
Array nullable

The bank details.Required and applicable if the payment method is set to BANK

string
Enumeration:
IBAN

IBAN code

NAME

Account name

NUMBER

Account Numer

BANK

Bank name

BANK_CODE

Bank code

BRANCH

Branch name

SWIFT
SORT_CODE
MANDATE
TYPE

Account type (Savings, Chekings)

COUNTRY
CURRENCY
card
string nullable

roadmap

wallet
Array nullable
string
Enumeration:
PHONE
EMAIL
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payment_gateways HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "8b724e8a-26a0-4c70-a959-b87d6acf8b50",
            "name": "PayPal",
            "description": "PayPal payment gateway",
            "connector": "PLUGIN",
            "integration_type": "PAYMENT_GATEWAYS",
            "enabled": true,
            "media_url": "crm.com/provider.png",
            "classifications": [
                "PAYMENTS"
            ],
            "payment_method_types": [
                "CARD"
            ],
            "details": {
                "account_debit": [
                    "SWIFT"
                ],
                "card": "",
                "wallet": [
                    "PHONE"
                ]
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Inventory
POST /warehouse_transactions
GET /warehouse_transactions
GET /warehouse_transactions/{id}
GET /stock
Create Warehouse Transaction
POST /warehouse_transactions

Creates a new warehouse transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
type
string required
Enumeration:
STOCK_IN

Moves items to the warehouse

STOCK_OUT

Removes items from warehouse

STOCK_ADJUSTMENT

Used to adjust the stock in the warehouse

code
string nullable

The warehouse transaction’s code. If not specified, then a unique and random 16-digit code is assigned

Example:
5467778889098987
supplier
string required nullable

The supplier of the products (applicable for stock in transactions)

Example:
AluxSat Provider
description
string nullable

A description for the warehouse transaction

Example:
A stock in transaction to import modems
contact_id
string GUID

The ID of the contact the device is sold/rented to. Applicable only for Stock out transactions

Example:
6A24D2B5E44F44B28451FE021FCAD51E
organisation_id
string GUID

The organisation (identifier) that items are sold/rented

Example:
135478f7-382e-2166-2873-1f5381725c3e
initiated_by
Object
entity
string
Enumeration:
INVOICE
CREDIT_NOTE
ORDER
id
string

The unique identifier of the initiating entity

items
Array

The items to be included in the warehouse transaction

Object
product_id
string GUID required

The product ID of the warehouse transaction item. Only stockable physical goods can be specified (traceable or not)

Example:
f02dfb43-261f-f16e-1f62-fb594c905e94
quantity
integer

The quantity to stock in or stock out. Required for non-traceable physical goods. For traceable physical goods the quantity is calculated based on th enumber of device serial numbers

Example:
10
unit_cost
number

The cost per unit (applicable only for stock in transaction)

Example:
10.5
adjust_type
string

Defines how the stock balance will be adjusted by this transaction. Applicable only for Stock Adjustments.

Enumeration:
+

Stock will be increased

-

Stock will be decreased

Example:
+
devices
Array
Object
serial_number
string
electronic_id
string

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The warehouse transaction identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/warehouse_transactions HTTP/1.1 

Content-Type: application/json

{
    "type": "STOCK_IN",
    "warehouse_id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "code": "5467778889098987",
    "supplier": "AluxSat Provider",
    "description": "A stock in transaction to import modems",
    "contact_id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "order_id": "JHDKJHSDKJHSKJH",
    "retailer_id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "initiated_by": {
        "entity": "CREDIT_NOTE",
        "entity_id": ""
    },
    "items": [
        {
            "product_id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "quantity": 10,
            "unit_cost": 10.5,
            "adjust_type": "+",
            "item_id": ""
        }
    ]
}
List Warehouse Transactions
GET /warehouse_transactions

Search for warehouse transactions. Transactions of a single warehouse can be retreived.

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

The value of the search. Warehouse transactions can be found using their code

product_id
string GUID optional

The ID of the product

Example:
6A24D2B5E44F44345651FE021FCAD51E
type_id
string optional

Unique identifier of the product type. If specified, then retrieve all warehouse transactions that include products of the specified product type

transaction_date
integer optional

The warehouse transaction date(s)

type

The warehouse transaction’s type

Collection format: csv
user_id
string optional

The user who performed the warehouse transaction

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string

The warehouse transaction identifier

Example:
6A24D2B5E44F44345651FE021FCAD51E
code
string

The warehouse transaction’s code. By default, warehouse transactions have a unique and random 16-digit code

Example:
4345600003321234
description
string

A description for the warehouse transaction

Example:
A stock in transaction to import modems
type
string
Enumeration:
STOCK_IN

Moves items to the warehouse

STOCK_OUT

Removes items from warehouse

STOCK_ADJUSTMENT

Used to adjust the stock in the warehouse

number_of_items
integer

Number of items (products) moved through the warehouse transaction

Example:
1000
performed_date
integer

The date on which the warehouse transaction was performed

Example:
1618857652
performed_by
Object
id
string GUID

The user identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The user full name

Example:
Maria Smith
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/warehouse_transactions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "6A24D2B5E44F44345651FE021FCAD51E",
            "code": "4345600003321234",
            "description": "A stock in transaction to import modems",
            "type": "STOCK_IN",
            "number_of_items": 1000,
            "performed_date": 1618857652,
            "performed_by": {
                "id": "6A24D2B5E44F44345651FE021FCAD51E",
                "name": "Jane Smith"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Warehouse Transaction
GET /warehouse_transactions/{id}

Get details for a specific warehouse transaction.

Path variables

id
string GUID required

The ID of the warehouse transaction to be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 OK

The request has succeeded

Body
Object
id
string

The warehouse transaction identifier

Example:
34545E44F44B28451FE021FCAD51E
code
string

The warehouse transaction’s code. By default, this is a unique and random 16-digit code

Example:
434000321934812
description
string

The warehouse transaction’s description

Example:
Stock in HD Receivers April 2021
supplier
string

The name of the supplier. Applicable only for Stock In transactions

Example:
AluxSat Provider
type
string
Enumeration:
STOCK_IN

Moves items to the warehouse

STOCK_OUT

Removes items from warehouse

STOCK_ADJUSTMENT

Used to adjust the stock in the warehouse

total_cost
number

The total cost of the warehouse transaction

Example:
99.99
currency
string

The twarehose transaction’s currency

Example:
EUR
performed_date
integer

The date on which the warehouse transaction was performed

Example:
1618859668
performed_by
Object
id
string GUID

The user identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The user full name

Example:
Maria Smith
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
organisation
Object
id
string GUID

The retailer’s unique identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The retailer’s name

Example:
SmartCom Co.
items
Array

The list of items included in the warehouse transaction

Object
product
Object
id
string GUID

The product identifier

Example:
e283a863-18e1-7cae-48c4-7433bf28cf97
sku
string

The product SKU code

Example:
ABC-12345
name
string

The product name

Example:
ABC
quantity
integer

The products’ quantity. Applicable for Stock In and Stock Out transactions

Example:
10
unit_cost
number

The unit cost per product. Applicable for Stock In and Stock Out transactions

Example:
10.99
total_cost
number

The total cost per warehouse transaction item. Applicable for Stock In and Stock Out transactions

Example:
109.9
adjust_type
string

Applicable only for Stock Adjustments. Indicates whether the specified products are added or removed from the warehouse’s stock balance

Enumeration:
+
-
Example:
+
devices
Array
Object
serial_number
string
electronic_id
string
initiated_by
Object

The entity that triggered the warehouse transaction

entity
string
Enumeration:
INVOICE
CREDIT_NOTE
ORDER
entity_id
string

The unique identifier of the entity

entity_number
string

The number of the entity

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/warehouse_transactions/6A24D2B5E44F44B28451FE021FCAD51E HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "34545E44F44B28451FE021FCAD51E",
    "code": "434000321934812",
    "description": "Stock in HD Receivers April 2021",
    "supplier": "AluxSat Provider",
    "type": "STOCK_IN",
    "total_cost": 99.99,
    "currency": "EUR",
    "performed_date": 1618859668,
    "performed_by": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E",
        "name": "Maria Smith"
    },
    "warehouse": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E",
        "name": "Nicosia headquarters"
    },
    "contact": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E",
        "code": "C0000102",
        "name": "John Smith"
    },
    "retailer": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E",
        "name": "SmartCom Co."
    },
    "items": [
        {
            "product": {
                "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                "sku": "HDRECEIVER",
                "name": "HD Receiver"
            },
            "quantity": 10,
            "unit_cost": 10.99,
            "total_cost": 109.9,
            "adjust_type": "+"
        }
    ],
    "initiated_by": {
        "entity": "ORDER",
        "entity_id": "",
        "entity_number": ""
    }
}
Get Stock Balance
GET /stock

Retrieves the stock balance

Request parameters

product_id
string GUID optional

The product for which the stock will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E
product_family_id
string GUID optional

The product family for which the stock will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E
product_type_id
string GUID optional

The product type for which the stock will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E
is_traceable
boolean optional

Filter based on whether products to be retrieved should be traceable or not

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
stock_information
Object
product
Object
id
string GUID

The ID of the product

Example:
6A24D2B5E44F44B28451FE021FCAD51E
sku
string

The sku of the product

Example:
sku
name
string

The name of the product

Example:
Set-top-box
is_traceable
boolean

Defines whether the product is traceable

Example:
true
number_of_variants
integer

Applicable only for Composite products. Defines the number of variant products also available in stock

Example:
3
composite_product
Object

Applicable only for variant products as it shpws the composite product

id
string
sku
string
name
string
stock_balance
integer

Defines the quantity of products that exist in the warehouse

Example:
100
latest_cost_per_unit
number

Defines the latest cost per unit sold on most recent invoice

Example:
9.99
average_cost_per_unit
number

Defines the average cost per unit

Example:
3.99
currency
string
Example:
EUR
rented
integer
reserved
integer
dispatched
integer
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/stock HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "warehouse": {
                "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                "name": "",
                "owned_by": {
                    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                    "name": "ORGANISATION"
                }
            },
            "stock_information": {
                "product": {
                    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                    "sku": "sku",
                    "name": "Set-top-box",
                    "is_traceable": "true"
                },
                "stock_balance": 100,
                "latest_cost_per_unit": 9.99,
                "average_cost_per_unit": 3.99,
                "currency": "EUR"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Leads
POST /leads
PUT /leads/{id}
DELETE /leads/{id}
GET /leads
GET /leads/{id}
GET /leads/{id}/queue_statuses
POST /leads/{id}/pipeline_stage
POST /leads/{id}/actions
POST /leads/bulk_update
PUT /leads/merge/{id}
Create Lead
POST /leads

Create a new lead

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
title
string required

A unique title for the lead

Example:
Watch It - new subscriptions lead (London)
pipeline_id
string GUID required

The lead pipeline unique id.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
pipeline_stage_id
string GUID required

The unique id of the current pipeline stage the lead is at.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
description
string

A description of the lead.

Example:
The client has an existing software but is looking for a better solution due to expansion.
value
number

The potential value of the lead if it’s won.

Example:
10000
currency_code
string

The currency of the lead value (could be in the lead’s currency)

Example:
GBP
expected_close_date
integer epoch

The expected closing date for the lead.

Example:
98765342
assign_to
Object nullable
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
owner_id
string

to be replaced by owner

custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The lead identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads HTTP/1.1 

Content-Type: application/json

{
    "title": "Watch It - new subscriptions lead (London)",
    "pipeline_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "pipeline_stage_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "description": "The client has an existing software but is looking for a better solution due to expansion.",
    "value": 10000,
    "currency_code": "GBP",
    "expected_close_date": 98765342,
    "assign_to": {
        "user_id": "1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf",
        "team_id": "a43f08ca-998b-afbc-6ed4-c9dc2d136935"
    },
    "owner_id": "",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Update Lead
PUT /leads/{id}

Update the information for a lead.

Path variables

id
string required

The GUID of the lead to be updated

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
title
string required

The unique title of the lead

Example:
Baker's Group of Companies - rewards lead
description
string

A brief description of the lead.

Example:
The customer is keen to implement the rewards software in time for their opening.
contact_id
string GUID

The GUID of the contact linked to the Lead (optional)

Example:
14B48204E5B44589AE99CC351BC46A2A
value
number

The potential value of the lead if it’s won.

Example:
10000
currency_code
string

The currency of the value of the lead (could be in the lead’s currency)

Example:
GBP
expected_close_date
integer epoch

The expected closing date for the lead.

Example:
98765342
owner_id
string GUID required

The GUID of lead owner, must be a system user.

Example:
M121E31269B76D7A65ACCE45B2E68DFD
assign_to
Object nullable
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
Examples

Responses

200 OK
Body
Object
id
string GUID

The lead identifier

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/leads/HPA1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "title": "Baker's Group of Companies - rewards lead",
    "description": "The customer is keen to implement the rewards software in time for their opening.",
    "contact_id": "14B48204E5B44589AE99CC351BC46A2A",
    "value": 10000,
    "currency_code": "GBP",
    "expected_close_date": 98765342,
    "owner_id": "M121E31269B76D7A65ACCE45B2E68DFD"
}
Delete Lead
DELETE /leads/{id}

Delete a single lead

Path variables

id
string GUID required

The GUID of the lead to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/leads/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 
List Leads
GET /leads

Retrieve all leads

Request parameters

page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
sort
string optional

Defines the attribute to be used for sorting the results

Enumeration:
TITLE
NAME
PIPELINE_STAGE
CLOSE_DATE
OWNER
search_value
string optional

Search for a lead using Title, Organisation, Contact person’s name

Example:
Baker's Group of Companies
pipeline_id
string optional

The lead pipeline GUID (to view leads)

Example:
0966F684B0269AD91CEEE83D6E0804A3
pipeline_stage_id
string GUID optional

The pipeline stage GUID (so that filtering can be performed using pipeline stage)

Example:
CEEE83D6E0804A30966F684B0269AD91
statuses
string optional

Filter leads based on status - comma separated (OPEN, WON, LOST)

Example:
OPEN
expected_close_date
string optional

Filter by expected closing date of the lead

Enumeration:
expected_close_date[gt]

Returns results where the expected closing date is greater than this value

expected_close_date[gte]

Returns results where the expected closing date is greater than or equal to this value

expected_close_date[lt]

Returns results where the expected closing date is less than this value

expected_close_date[lte]

Returns results where the expected closing date is less then or equal to this value

is_overdue
boolean optional

Display those leads whose expected closing date has passed, but still have a status of OPEN.

Example:
true
contact_id
string optional

The GUID of the Contact associated to the Lead (if it exists)

Example:
14B48204E5B44589AE99CC351BC46A2A
tag_ids
array of string optional

The ids of the tags to filter by.

Collection format: csv
owner_id
string optional

Filter by unique owner (user) id.

Example:
4613eb36-e5e8-46e8-9517-b1a31e86c89c
assign_to_user_id
string GUID optional

Filters based on specific assign to user

Example:
c45903ff-4a00-49bd-93b4-6b2f0373ce20
assign_to_team_id
string GUID optional

Filters based on specific assign to team

Example:
5beb415c-3246-1a10-f806-3f975e4898dc
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
include_tags
boolean optional

Defines whether tags fields should be retrieved or not (via List/Get APIs)

Allow empty value: true
Default:
false
Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The lead unique identifier

Example:
LEM1E31269B76D7A65ACCE45B2E68DFD
title
string

The title of the lead

Example:
Burger Time Restaurants (chain)
status
string

The status of the lead (OPEN, WON, LOST)

Example:
OPEN
pipeline
Object

Lead pipeline information

id
string GUID

The lead pipeline id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The lead pipeline name

Example:
New large-scale business rewards lead
pipeline_stage
Object

Current lead pipeline stage information

id
string GUID

The current pipeline stage unique id

Example:
KVX1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the current pipeline stage the lead is at

Example:
Proposal submitted
description
string

A brief description of the lead

Example:
Lead was referred by our client Baker's Dozen
contact
Object

Details of the contact linked to the lead (if it exists)

id
string

The GUID of the Contact linked to the Lead (if a Contact link exists)

Example:
14B48204E5B44589AE99CC351BC46A2A
name
string

The name of the contact linked to the lead (only if contact id exists)

Example:
John Smith
value
integer

The potential value of the lead if it’s won

Example:
15000
expected_close_date
integer epoch

The expected closing date of the lead

Example:
98765342
lost_reason
Object

Reason for losing the lead. Availble only if the lead status is LOST.

id
string GUID

The lost reason unique id

Example:
LLO1E31269B76D7A65ACCE45B2E68DFD
reason
string

Lost lead reason

Example:
Lost to competitor
assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/leads HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "LEM1E31269B76D7A65ACCE45B2E68DFD",
            "title": "Burger Time Restaurants (chain)",
            "status": "OPEN",
            "pipeline": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "New large-scale business rewards lead"
            },
            "pipeline_stage": {
                "id": "KVX1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Proposal submitted"
            },
            "description": "Lead was referred by our client Baker's Dozen",
            "contact": {
                "id": "14B48204E5B44589AE99CC351BC46A2A",
                "name": "John Smith"
            },
            "value": 15000,
            "expected_close_date": 98765342,
            "lost_reason": {
                "id": "LLO1E31269B76D7A65ACCE45B2E68DFD",
                "reason": "Lost to competitor"
            },
            "assign_to": {
                "user": {
                    "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
                    "name": "John Doe",
                    "username": "j_doe@crm.com"
                },
                "team": {
                    "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
                    "name": "Support"
                }
            },
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Lead
GET /leads/{id}

Retrieve the information for a specific lead.

Path variables

id
string required

The lead identifier (GUID) of the lead to be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The lead GUID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
title
string

The title of the lead, mandatory and unique.

Example:
Burger Time Restaurants (chain)
status
string

The status of the lead (OPEN, WON, LOST)

Example:
OPEN
pipeline
Object

The lead pipeline information

id
string GUID

The lead pipeline id

Example:
LMP1E31269B76D7A65ACCE45B2E68DFD
name
string

The pipeline name

Example:
New large-scale business rewards lead
pipeline_stage_id
string

The unique id of the current pipeline stage the lead is in

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
description
string

A brief description of the lead

Example:
Lead was referred by our client Baker's Dozen
contact
Object

Details of the Contact linked to the Lead (if avaialble)

id
string GUID

GUID of Contact

Example:
14B48204E5B44589AE99CC351BC46A2A
name
string

Contact name

Example:
John
surname
string

Contact surname

Example:
Smith
value
number

The potential value of the lead if it’s won

Example:
15000
expected_close_date
integer epoch

The expected closing date of the lead

Example:
98765342
lost_reason
Object
name
string

The reason for losing the lead

Example:
Lost to competitor
assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/leads/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "title": "Burger Time Restaurants (chain)",
    "status": "OPEN",
    "pipeline": {
        "id": "LMP1E31269B76D7A65ACCE45B2E68DFD",
        "name": "New large-scale business rewards lead",
        "pipeline_stage_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
    },
    "description": "Lead was referred by our client Baker's Dozen",
    "contact": {
        "id": "14B48204E5B44589AE99CC351BC46A2A",
        "name": "John",
        "surname": "Smith"
    },
    "value": 15000,
    "expected_close_date": 98765342,
    "lost_reason": {
        "name": "Lost to competitor"
    },
    "assign_to": {
        "user": {
            "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
            "name": "John Doe",
            "username": "j_doe@crm.com"
        },
        "team": {
            "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
            "name": "Support"
        }
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
List Lead Pipeline Stages
GET /leads/{id}/queue_statuses

Retrieve all the pipeline stages a lead has progressed through.

Path variables

id
string required

The GUID of the lead whose pipeline stages will be retrieved

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
pipeline_stage_id
string

The pipeline stage id

Example:
558269B76D7A65ACCE45B2E68DFD
name
string

Name of the pipeline stage

Example:
Proposal Submitted
date_achieved
integer epoch

Date of achieving this pipeline stage

Example:
98765342
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/leads/HPA1E31269B76D7A65ACCE45B2E68DFD/queue_statuses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "pipeline_stage_id": "558269B76D7A65ACCE45B2E68DFD",
            "name": "Proposal Submitted",
            "date_achieved": 98765342
        }
    ]
}
Update Lead Pipeline Stage
POST /leads/{id}/pipeline_stage

Change the pipeline stage of a lead (e.g. progress a lead).

Path variables

id
string required

The GUID of the lead whose pipeline stage will be changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
pipeline_stage_id
string GUID required

The new pipeline stage ID

Example:
CEEE83D6E0804A30966F684B0269AD91
date_achieved
integer epoch

Defaults to current date & time

Example:
1583846865
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the lead whose pipeline stage was changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/HPA1E31269B76D7A65ACCE45B2E68DFD/pipeline_stage HTTP/1.1 

Content-Type: application/json

{
    "pipeline_stage_id": "CEEE83D6E0804A30966F684B0269AD91",
    "date_achieved": 1583846865
}
Perform Lead Actions
POST /leads/{id}/actions

Change the status of a lead.

Path variables

id
string required

The GUID of the lead whose status is to be changed.

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
status
string required

The new lead status

Enumeration:
OPEN

The lead is still in progress

WON

The lead has been won

LOST

The lead has been lost

Example:
LOST
lost_reason_id
string GUID

Required only when a lead has a status of ‘lost’

Example:
4AD9C84FA60F9FE407140E20F707726A
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the lead whose status was changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/HPA1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "status": "LOST",
    "lost_reason_id": "4AD9C84FA60F9FE407140E20F707726A"
}
Bulk Update Leads
POST /leads/bulk_update

Change the lead pipeline stage, owner, expected close date of one or more leads that have been selected as part of a bulk update action

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
leads
Array

A list of leads GUID codes to be updated

string
Min length: 1
Example:
MH01E31269B76D7A65ACCE48D80, S332E31269B76D7AE45B2E689UT, 74D9C84FA6007140E20F707726A
pipeline_stage_id
string GUID

The new pipeline stage unique id (optional).

Example:
31269B76D7A65ACCE45B2E68DFD
owner_id
string

The GUID of the new lead owner (optional).

Example:
L1269B76D7A65ACCE45B2E68DFD
expected_close_date
integer epoch

The new expected close date (optional).

Example:
98765342
Examples

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/bulk_update HTTP/1.1 

Content-Type: application/json

{
    "leads": [
        "MH01E31269B76D7A65ACCE48D80, S332E31269B76D7AE45B2E689UT, 74D9C84FA6007140E20F707726A"
    ],
    "pipeline_stage_id": "31269B76D7A65ACCE45B2E68DFD",
    "owner_id": "L1269B76D7A65ACCE45B2E68DFD",
    "expected_close_date": 98765342
}
Merge Leads
PUT /leads/merge/{id}

Merge two leads into one

Path variables

id
string required

The id of the target lead (i.e. lead to be kept)

Example:
E901E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
source_id
string GUID

The id of the Lead to be merged into the target Lead and then deleted.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the successfully updated lead

Example:
E901E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/leads/merge/E901E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "source_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "E901E31269B76D7A65ACCE45B2E68DFD"
}
Lead Notes
POST /leads/{id}/notes
PUT /leads/{id}/notes/{note_id}
DELETE /leads/{id}/notes/{note_id}
GET /leads/{id}/notes
Create Lead Note
POST /leads/{id}/notes

Create a new note for a lead

Path variables

id
string required

Lead GUID for which the note is to be created

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
note
string required

The note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
pinned
boolean

Pinned notes appear at the top of the notes list. True = pin note, false = don’t pin note

Example:
true
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The identifier for the note created

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/6A24D2B5E44F44B28451FE021FCAD51E/notes HTTP/1.1 

Content-Type: application/json

{
    "note": "After my telephone conversation with Zack this morning, it was decided that....",
    "pinned": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Lead Note
PUT /leads/{id}/notes/{note_id}

Update a note for a lead.

Path variables

id
string required

The lead GUID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
note_id
string required

The note GUID

Example:
SMA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
note
string

The actual note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
pinned
boolean

Pinned notes appear at the top of the notes list.

Example:
true
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the updated note

Example:
SMA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/leads/CAD1E31269B76D7A65ACCE45B2E68DFD/notes/SMA1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "note": "After my telephone conversation with Zack this morning, it was decided that....",
    "pinned": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "SMA1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Lead Note
DELETE /leads/{id}/notes/{note_id}

Delete a single note for a lead

Path variables

id
string GUID required

The GUID of the lead

Example:
PT19C84FA60F9FE407140E20F707726A
note_id
string required

The GUID of the note to be deleted

Example:
XOP9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/leads/PT19C84FA60F9FE407140E20F707726A/notes/XOP9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 
List Lead Notes
GET /leads/{id}/notes

Retrieve all notes for a single lead

Path variables

id
string required

The GUID of the lead whose notes are to be retrieved

Example:
TFD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
sort
string optional

Defines the attribute to be used for sorting the results

Default:
CREATED_DATE
Example:
CREATED_DATE, UPDATED_DATE, USER

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The note unique identifier

Example:
LEP1E31269B76D7A65ACCE45B2E68D34
created_by
Object

Details of the user who created the note

id
string

The GUID of the user who created the note

Example:
1121E31269B76D7A65ACCE45B2E68KP1
username
string

The name of the user who created the note

Example:
Sam Jackson
created_on
string epoch

Date and time the note was created

Example:
98765775
updated_on
string epoch

Date and time the note was updated

Example:
98765795
pinned
boolean

Pinned notes appear at the top of the notes list

Example:
true
note
string

The note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/leads/TFD1E31269B76D7A65ACCE45B2E68DFD/notes HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "LEP1E31269B76D7A65ACCE45B2E68D34",
            "created_by": {
                "id": "1121E31269B76D7A65ACCE45B2E68KP1",
                "username": "Sam Jackson"
            },
            "created_on": "98765775",
            "updated_on": "98765795",
            "pinned": "true",
            "note": "After my telephone conversation with Zack this morning, it was decided that...."
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Lead Attachments
POST /leads/{id}/files
DELETE /leads/{id}/files/{file_id}
GET /leads/{id}/files
Add Leads Attachment File
POST /leads/{id}/files

Connect an uploaded file to an existing lead

Path variables

id
string GUID required

The lead (identifier) that file will be attached

Example:
66451204-4404-894c-4dc6-486c540ece40

Notes

Uploading files into CRM is made based on the following flow & API calls

  1. Upload File Signature
  2. Connect a file to a Lead

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required nullable

The file (identifier) to be attached

Example:
30526723-24a3-e4e3-1a75-b26b1b41f05c
url
string required nullable

URL of the file to be attached

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
description
string nullable

The file description

Example:
Screenshot sent by customer

Responses

200 OK
Body
Object
id
string GUID

The lead identifier

Example:
66451204-4404-894c-4dc6-486c540ece40
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "file_id": "30526723-24a3-e4e3-1a75-b26b1b41f05c",
    "description": "this is a small description"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "66451204-4404-894c-4dc6-486c540ece40"
}
Delete Lead Attachment File
DELETE /leads/{id}/files/{file_id}

Delete a specific lead attachment file

Path variables

id
string GUID required

The lead (identifier) that file will be deleted

Example:
66451204-4404-894c-4dc6-486c540ece40
file_id
string GUID required

The attachment file (identifier) that will be deleted

Example:
04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/leads/66451204-4404-894c-4dc6-486c540ece40/files/04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Leads Attachment Files
GET /leads/{id}/files

Retrieve all attachment files for a specific lead

Path variables

id
string GUID required

The lead (identifier) that files will be retrieved

Example:
66451204-4404-894c-4dc6-486c540ece40

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The attachment identifier

Example:
3ae9d64a-8a3b-f1e1-eed6-05b307f926fb
mime
string

The mime type of the uploaded file

Enumeration:
csv
doc
docx
xls
xlsx
pdf
log
txt
png
jpg
jpeg
svg
description
string

The attachement description

Example:
Screenshot sent by customer
file
Object

The attachement file details

id
string GUID

The file identifier

Example:
0317868f-28f8-9f56-d248-5a78718b38cc
url
string

The file URL endpoint

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
name
string

The file name

Example:
img.png
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/leads/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
            "mime": "png",
            "description": "this is a brief description of this image",
            "file": {
                "id": "0317868f-28f8-9f56-d248-5a78718b38cc",
                "name": "img.png"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Lead Tags

The following functionality relates to tags for leads

POST /leads/{id}/tags
PUT /leads/{id}/tags
DELETE /leads/{id}/tags/{tag_id}
GET /leads/{id}/tags
Add tags to a lead
POST /leads/{id}/tags

The following process adds tags to a lead.

Path variables

id
string required

The leads GUID

Example:
HRDGSWRSFVSDSDBSDSSDDE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
FDHNFDBR675765ghdh
Example 1
POST https://sandbox.crm.com/backoffice/v1/leads/HRDGSWRSFVSDSDBSDSSDDE/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "FDHNFDBR675765ghdh"
        }
    ]
}
Update tags for a lead
PUT /leads/{id}/tags

The following process updates tags for a lead.

Path variables

id
string required

The lead GUID

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
JKGSJGFKDGJKFGFSJK
Example 1
PUT https://sandbox.crm.com/backoffice/v1/leads/{id}/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "JKGSJGFKDGJKFGFSJK"
        }
    ]
}
Delete Lead Tag
DELETE /leads/{id}/tags/{tag_id}

Deletes a tag on a lead.

Path variables

id
string required

The id of the leads.

Example:
JFGJKSFGJFSGH
tag_id
string required

The id of the tag

Example:
KJDFHKJGFSJHG
Example 1
DELETE https://sandbox.crm.com/backoffice/v1/leads/JFGJKSFGJFSGH/tags/KJDFHKJGFSJHG HTTP/1.1 
Get tags for lead
GET /leads/{id}/tags

The following process retrieves the tags for a lead

Path variables

id
string required

Responses

200 OK
Body
Object
content
Array
Object
id
string

the tag ID

Example:
JKGJHFSDJHGDSJHGA
name
string

Name of Tag

Example:
Maintenance
colour
string

Colour of tag

Example:
The colour of the tag
Example 1
GET https://sandbox.crm.com/backoffice/v1/leads/{id}/tags HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JKGJHFSDJHGDSJHGA",
            "name": "Maintenance",
            "colour": "The colour of the tag"
        }
    ]
}
Orders
POST /orders
PUT /orders/{id}
DELETE /orders/{id}
GET /orders
GET /orders/{id}
PUT /orders/{id}/actions
Make an Order
POST /orders

Creates a new Order for a contact based on an order’s estimation

Notes

The following APIs should be called in order to make an order

  1. Order Fulfillment
  2. Orders
  3. Make an Order

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
estimation_id
string GUID required

The estimation_id as this is returned back by the estimates/order Web API

Example:
37b56acf-665c-1112-93fc-163b3639bcbe
payments
Array required
Object
payment_method_type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
amount
number
Example:
12.21
payment_method_id
string GUID nullable
Example:
5d6c838c-ef87-703c-a587-844c94b61f71
payment_token
string nullable
Example:
paytoken12344
notes
string nullable

The order general notes

Example:
Lorem Ipsum
use_wallet_funds
boolean nullable

Defines whether available wallet funds can be used on the order total amount. If wallet funds do not cover the entire order amount, then payment method will be used

Default:
false
Example:
true
wallet_funds_amount
number nullable

Defines a specific amount that should be used on the order total amount (applicable only if “use_wallet_funds” is true)

Example:
11.99
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
devices
Array

A list of devices unique identifiers

Unique items: YES
Object
product_id
string
device_ids
Array of string

Responses

200 200

OK

Body
Object
id
string GUID

The unique identifier of the new order

Example:
f3076649-5350-4215-9278-ba95452a72f7
number
string
estimated_delivery_time
Object
time_to_deliver
integer
Example:
20
uot
string
Example:
MINUTES
delivery_at
integer epoch

The actual delivery time

Example:
1599224678
fulfilled_by
Object
id
string GUID

The organisation identifier

Example:
f3076649-5350-4215-9278-ba95452a72f7
name
string

The name of the organisation

Example:
Bro Burgers
phone
string

The organisation’s phone number

Example:
+6934222321
address
Object

Information about the organisation’s location

id
string GUID

The location identifier

Example:
LOC123456234567345674567895678IK
name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
care_of
string

The care of information of the location

Example:
c/o Company
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/orders HTTP/1.1 

Content-Type: application/json

{
    "estimation_id": "37b56acf-665c-1112-93fc-163b3639bcbe",
    "payments": [
        {
            "payment_method_type": "ACCOUNT",
            "paid_on": "ON_ORDER",
            "payment_method_id": "5d6c838c-ef87-703c-a587-844c94b61f71",
            "amount": 12.21,
            "payment_token": "paytoken12344"
        }
    ],
    "notes": "",
    "use_wallet_funds": "true",
    "wallet_funds_amount": 11.99,
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f3076649-5350-4215-9278-ba95452a72f7",
    "number": "",
    "estimated_delivery_time": {
        "time_to_deliver": 20,
        "uot": "MINUTES",
        "delivery_at": 1599224678
    },
    "fulfilled_by": {
        "id": "f3076649-5350-4215-9278-ba95452a72f7",
        "name": "Bro Burgers",
        "phone": "+6934222321",
        "address": {
            "id": "LOC123456234567345674567895678IK",
            "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",
            "care_of": "c/o Company",
            "lat": 35.157115,
            "lon": 33.313719,
            "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    }
}
Update Order
PUT /orders/{id}

Updates an existing (single) Order

Path variables

id
string GUID required

The order identifier that will be updated

Example:
f3076649-5350-4215-9278-ba95452a72f7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
notes
string
category_id
string GUID
Example:
f3076649-5350-4215-9278-ba95452a72f7
payment_method_type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
payment_method_id
string

The contact’s payment method. Applicable and required for online payment methods - Cards, Account Debits and Wallets

order_items
Array
Object
product_id
string GUID
Example:
f3076649-5350-4215-9278-ba95452a72f7
quantity
integer
Example:
1
notes
string
components
Array
Object
product_id
string GUID
Example:
f3076649-5350-4215-9278-ba95452a72f7
quantity
integer
Example:
2
variant_attributes
Array
Object
key
string GUID
Example:
f3076649-5350-4215-9278-ba95452a72f7
value
string
Example:
Small
id
string

Unique identifie rof the ordered item

status
Object
id
string
comment
string

The comment inserted when a new status is achieved.

date_achieved
string epoch
external_reference
string

A reference provided by external systems

Example:
REF1234
discount
Object

An updated ad-hoc discount

amount
number
type
string
Enumeration:
AMOUNT
PERCENTAGE
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
Examples

Responses

200 OK
Body
Object
id
string GUID

The order identifier

Example:
f3076649-5350-4215-9278-ba95452a72f7
approval_requests
Array

Determines whether approval reuqests are applied or not, if not null an approval is requested

Object
id
string GUID

The apporval request identifier

Example:
3a4aad81-e5c2-72b7-3a86-903239d08767
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/orders/f3076649-5350-4215-9278-ba95452a72f7 HTTP/1.1 

Content-Type: application/json

{
    "notes": "",
    "category_id": "f3076649-5350-4215-9278-ba95452a72f7",
    "payment_method_type": "CHEQUE",
    "payment_method_id": "",
    "order_items": [
        {
            "product_id": "f3076649-5350-4215-9278-ba95452a72f7",
            "quantity": 1,
            "notes": "",
            "components": [
                {
                    "product_id": "f3076649-5350-4215-9278-ba95452a72f7",
                    "quantity": 2
                }
            ],
            "variant_attributes": [
                {
                    "key": "f3076649-5350-4215-9278-ba95452a72f7",
                    "value": "Small"
                }
            ],
            "id": ""
        }
    ],
    "status": {
        "id": "",
        "comment": "",
        "date_achieved": ""
    },
    "external_reference": "REF1234",
    "discount": {
        "amount": 1,
        "type": "AMOUNT"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f3076649-5350-4215-9278-ba95452a72f7",
    "approval_requests": [
        {
            "id": "3a4aad81-e5c2-72b7-3a86-903239d08767"
        }
    ]
}
Delete Order
DELETE /orders/{id}

Deletes an Order. A single order is deleted per Web API call

Path variables

id
string GUID required

The order identifier that will be deleted

Example:
f3076649-5350-4215-9278-ba95452a72f7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Examples

Responses

200 OK
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/orders/{id} HTTP/1.1 

Content-Type: application/json

HTTP/1.1 200 OK 
List Orders
GET /orders

Retrieve a list of orders based on search criteria (e.g. today’s new orders).

Request parameters

number
string optional

Filters based on the order number

Example:
O100012
life_cycle_state

Fitlers based on the order state

Collection format: csv
Unique items: YES
Example:
NEW
supply_method
string optional

Defines how order was/will be provided

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
contact_id
string GUID optional

Filters orders based on the contact that placed such orders

Example:
8b069359-3e76-e036-1d78-46a683620998
is_favorite
boolean optional

Filters orders based on whether are marked as favorite or not

Example:
true
created_on
string optional

Filters orders based on created date

Enumeration:
created_on[gt]

Returns results where the created date is greater than this value

created_on[gte]

Returns results where the created date is greater than or equal to this value

created_on[lt]

Returns results where the created date is less than this value

created_on[lte]

Returns results where the created date is less then or equal to this value

fulfilled_by
string GUID optional

Filter orders based on the organisation that will fulfill such orders

Example:
9547012f-8d1a-3ec9-d3f5-2ba48788424c
fulfilled_by_tap_code
string optional

Filter orders based on the organisation’s tap code that will fulfill such orders (tap should be active)

Example:
TAP-001
search_value
string optional

Search for orders based on their number and contact name

include_order_items
boolean optional
Default:
false
from_date
integer epoch optional

Filter orders based on created from date

Example:
1623922340
to_date
integer epoch optional

Filter orders based on created to date

Example:
1623922340
include_address
boolean optional
Default:
false
order_country
string optional

The country (code) in which the order was fulfilled by

Example:
CYP
queue_id
string optional

The order queue

status_id
string optional

The status of the order

Example:
KHJKJdHKAJH
ponr_reached
boolean optional

Point of no return reached

include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
organisation_id
string optional

The organisation that placed the order

include_approvals
boolean optional

Defines whether approval requests information should be retrieved or not

Example:
true
approval_state
string optional

Filter based on approval request state

Enumeration:
PENDING
APPROVED
REJECTED
address
string optional

Search for an order using its delivery address

Example:
Main Street 34
address_name
string optional

Search for an order using the delivery address’s name

Example:
Main Store

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The order identifier

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
number
string

The order reference number

Example:
O11101
life_cycle_state
string

The order life cycle state

Enumeration:
NEW
IN_PROGRESS
COMPLETED
CANCELLED
ON_HOLD
notes
string

The order general notes

Example:
Lorem Ipsum
number_of_milestones
integer
Example:
1
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
total_cost
number

The total cost of all order items. The cost equals to the total cost of the order’s invoice, taxes and discounts included

Example:
9.99
wallet_funds_amount
number

The amount that was used from wallet funds

Example:
1.59
total_before_discount
number

The order’s total amount before applying the discount. Includes the tax amount

amount_due
number

The amount due. This is the due amount of the order’s invoice, calculated cosidering its due date

Example:
9.99
amount_to_collect
number

The amount of money that was collected to pay off the order’s invoice. This amount equals to the order’s cost minus wallet funds (if any)

Example:
8.49
discount
Object

Total discount amount provided to the ordered items.

amount
number

Total discount amount excluding taxes. This amount equals to the sum of all discount amounts among all invoiced items. Note that this amount does not include the taxed amount.

amount_incl_tax
number

The total discount amount including taxes

currency
string
Example:
EUR
contact
Object
id
string GUID

The contact identifier

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
code
string

The contact code

Example:
C0001
name
string

The contact name

Example:
John Doe
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
category
Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
cancellation_reason
Object

Details about the reason that cancelled the order

id
string GUID

The cancellation reason identifier

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
name
string

The cvancellation reason

Example:
Void by customer
fulfilled_by
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
queue
Object

Details pertaining to the queue

id
string

id of the queue

name
string

name of the queue

status
Object
id
string
name
string
colour
string
ponr_reached
boolean

Defines whether the point of no return has been reached or not

Example:
true
order_items
Array
Object
id
string GUID
Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
notes
string
quantity
integer

The quantity of the ordered items

Example:
2
product
Object
id
string GUID
Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
sku
string

The product SKU

Example:
0123-112
name
string

The product name

Example:
Decoder
quantity
integer

How many products were ordered

Example:
2
price
number

The unit price as defined in the order’s Invoice,excluding taxed amount

Example:
1.7
tax_amount
number

The applied tax amount

Example:
0.08
cost_before_discount
number

The sub-total of the product before applying the discount. Tax amount is included

Example:
1.78
cost
number

The order item’s sub-total. The sub-total includes the discount amount i.e. the discount is deducted from the product’s price

Example:
3.4
discount
Object

The discount provided to the ordered item

amount
number

The applied discount amount excluding taxes

amount_incl_tax
number

The applied disocunt with its taxed amount

percentage
number

The applied discount percentage

classification
string

product type classification

Example:
EXPENSE_SERVICE
components
Array
Object
id
string GUID
Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
sku
string
name
string
quantity
integer
Example:
1
price
number
Example:
0.48
price_incl_tax
number
Example:
0.5
variant_attributes
Array
Object
key
string
Example:
size
name
string
Example:
Size
value
string
Example:
Grande
price_terms
Object
billing_period
Object
duration
string
Example:
1
uot
string
Example:
MONTHS
auto_renew
boolean
key_dates
Object
submitted_on
integer
Example:
1592809457
completed_on
integer
Example:
1592809457
cancelled_on
integer
Example:
1592809457
estimated_fulfillment_in
integer
Example:
30
estimated_fulfillment_UOT
string
Example:
MINUTES
estimated_fulfillment
integer epoch
Example:
1592809457
expires_on
integer epoch
Example:
1592809457
started_on
integer epoch
requested_date
integer epoch
number_of_items
integer

The number of items included in the Order

Example:
1
available_for_printing
boolean

Defines whether the orders are configured to be printed

Example:
true
is_printed
boolean

Defines whether the order has been printed successfully

Example:
true
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
order_provision
Object

Details about order provision

available_for_provision
boolean

Defines whether the order is configured to be provisioned

Example:
true
is_provisioned
boolean

Defines whether the order has been provisioned successfully (applicable only if the order is available for provision)

Example:
false
provisioner
string

Defines the integration on which the order has been provisioned (applicable only if the order is available for provision)

Enumeration:
TWINSOFT
ALOHA
external_reference
string

A reference identifier (usually an id) provided by an external system that provisioned this order

Example:
23434232345
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
approvals
Object

Details about the latest requested approval(s)

state
string

The approval request state

Enumeration:
PENDING
APPROVED
REJECTED
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Retrieve (new) Orders
Example 2

Retrieve today’s orders for a specific venue that are currently new

GET https://sandbox.crm.com/backoffice/v1/orders?life_cycle_state=NEW&fulfilled_by_tap_code=8269&created_on[gte]=1628456400 HTTP/1.1 

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "paging": {
        "page": 1,
        "size": 2,
        "total": 2
    },
    "content": [
        {
            "number": "A11636",
            "address": null,
            "currency": "EUR",
            "notes": "please add a couple napkins",
            "contact": {
                "id": "ed86f87f-3df2-4c83-8897-736c08536eb9",
                "name": "Sozos K",
                "code": "6562126827272730"
            },
            "category": null,
            "assignee": null,
            "discount": {
                "amount": 0.68,
                "amount_incl_tax": 0.72
            },
            "id": "970cc6bc-ca78-4f35-9fb7-09c81a42dfc7",
            "life_cycle_state": "NEW",
            "supply_method": "DELIVERY",
            "total_cost": 6.38,
            "wallet_funds_amount": 0.20,
            "amount_due": 6.18,
            "key_dates": {
                "id": null,
                "submitted_on": 1628500082,
                "completed_on": null,
                "cancelled_on": null,
                "expires_on": null,
                "requested_date": null,
                "started_on": null,
                "estimated_fulfillement": 1628507280,
                "estimated_fulfillement_in": 119,
                "estimated_fulfillment_UOT": "MINUTE"
            },
            "number_of_milestones": 1,
            "cancellation_reason": null,
            "fulfilled_by": {
                "id": "8967BAB2A75A456DA055D00111F97DFE",
                "name": "Store 1"
            },
            "is_favorite": false,
            "number_of_items": 3,
            "is_printed": true,
            "available_for_printing": null,
            "order_provision": {
                "provisioner": null,
                "available_for_provision": false,
                "is_provisioned": true
            },
            "amount_to_collect": 6.18,
            "total_before_discount": 7.10,
            "order_items": []
        },
        {
            "number": "A11635",
            "address": null,
            "currency": "EUR",
            "notes": null,
            "contact": {
                "id": "ed86f87f-3df2-4c83-8897-736c08536eb9",
                "name": "Sozos K",
                "code": "6562126827272730"
            },
            "category": null,
            "assignee": null,
            "discount": {
                "amount": 0.00,
                "amount_incl_tax": 0.00
            },
            "id": "16105370-9be8-412e-976c-f987c40254a6",
            "life_cycle_state": "NEW",
            "supply_method": "PICK_UP",
            "total_cost": 7.70,
            "wallet_funds_amount": null,
            "amount_due": 7.70,
            "key_dates": {
                "id": null,
                "submitted_on": 1628499814,
                "completed_on": null,
                "cancelled_on": null,
                "expires_on": null,
                "requested_date": null,
                "started_on": null,
                "estimated_fulfillement": 1628507014,
                "estimated_fulfillement_in": 120,
                "estimated_fulfillment_UOT": "MINUTE"
            },
            "number_of_milestones": 1,
            "cancellation_reason": null,
            "fulfilled_by": {
                "id": "8967BAB2A75A456DA055D00111F97DFE",
                "name": "Store 1"
            },
            "is_favorite": false,
            "number_of_items": 3,
            "is_printed": true,
            "available_for_printing": null,
            "order_provision": {
                "provisioner": null,
                "available_for_provision": false,
                "is_provisioned": true
            },
            "amount_to_collect": 7.70,
            "total_before_discount": 7.70,
            "order_items": []
        }
    ]
}
GET https://sandbox.crm.com/backoffice/v1/orders HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
            "number": "O11101",
            "life_cycle_state": "IN_PROGRESS",
            "notes": "Lorem Ipsum",
            "number_of_milestones": 1,
            "supply_method": "DELIVERY",
            "total_cost": 9.99,
            "wallet_funds_amount": 1.59,
            "total_before_discount": 1,
            "amount_due": 9.99,
            "amount_to_collect": 8.49,
            "discount": {
                "amount": 1,
                "amount_incl_tax": 1
            },
            "currency": "EUR",
            "contact": {
                "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
                "code": "C0001",
                "name": "John Doe"
            },
            "address": {
                "address_line_1": "Elia Papakyriakou",
                "address_line_2": "7 Tower Stars",
                "state_province_county": "Egkomi",
                "town_city": "Nicosia",
                "postal_code": "2015",
                "country": "CYP",
                "lat": 35.157115,
                "lon": 33.313719,
                "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
            },
            "category": {
                "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                "name": "Delivery Purchase"
            },
            "cancellation_reason": {
                "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
                "name": "Void by customer"
            },
            "fulfilled_by": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "queue": {
                "id": "",
                "name": ""
            },
            "status": {
                "id": "",
                "name": "",
                "colour": ""
            },
            "ponr_reached": true,
            "order_items": [
                {
                    "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
                    "notes": "",
                    "quantity": 2,
                    "product": {
                        "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
                        "sku": "0123-112",
                        "name": "Decoder",
                        "quantity": 2,
                        "price": 1.7,
                        "tax_amount": 0.08,
                        "cost_before_discount": 1.78,
                        "cost": 3.4,
                        "discount": {
                            "amount": 1,
                            "amount_incl_tax": 1,
                            "percentage": 1
                        },
                        "classification": "EXPENSE_SERVICE",
                        "components": [
                            {
                                "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
                                "sku": "",
                                "name": "",
                                "quantity": 1,
                                "price": 0.48,
                                "price_incl_tax": 0.5
                            }
                        ],
                        "variant_attributes": [
                            {
                                "key": "size",
                                "name": "Size",
                                "value": "Grande"
                            }
                        ],
                        "price_terms": {
                            "billing_period": {
                                "duration": "1",
                                "uot": "MONTHS"
                            },
                            "auto_renew": true
                        }
                    }
                }
            ],
            "key_dates": {
                "submitted_on": 1592809457,
                "completed_on": 1592809457,
                "cancelled_on": 1592809457,
                "estimated_fulfillment_in": 30,
                "estimated_fulfillment_UOT": "MINUTES",
                "estimated_fulfillment": 1592809457,
                "expires_on": 1592809457,
                "started_on": 1,
                "requested_date": 1
            },
            "number_of_items": 1,
            "available_for_printing": "true",
            "is_printed": "true",
            "custom_fields": [
                {
                    "key": "back_office",
                    "value": "0001-12345"
                }
            ],
            "order_provision": {
                "available_for_provision": "true",
                "is_provisioned": "false",
                "provisioner": "TWINSOFT"
            },
            "external_reference": "23434232345",
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Order
GET /orders/{id}

Retrieves detailed information of an Order. A single Order is retrieved per Web API call

Path variables

id
string GUID required

The order (identifier) that will be retrieved

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The order identifier

Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
number
string

The order number

Example:
ORDER1234
life_cycle_state
string

The order life cycle state

Enumeration:
NEW
IN_PROGRESS
COMPLETED
CANCELLED
ON_HOLD
notes
string

The order general notes

Example:
Lorem Ipsum
number_of_milestones
integer

The total number of milestones for the order

Example:
1
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
total_cost
number

The total cost of all order items including taxes and discounts. This is the total amount of the order’s Invoice.

Example:
5.99
wallet_funds_amount
number

The amount that was used from wallet funds

Example:
1.98
total_before_discount
number

Total amount of the invoice without the applied discount amount. Tax amount is included

amount_due
number

The amount due to be paid. The due amount is calculated based on the order’s Invoice due date

Example:
3.01
amount_to_collect
number

The amount of money that was collected to pay off the order’s invoice/s. This amount equals to the order’s cost minus wallet funds (if any), minus any payments made against this order.

discount
Object

Total discount amount applied through promotions and ad-hoc discount

amount
number

Total discount amount excluding taxes. This amount equals to the sum of all discount amounts among all invoiced items. Note that this amount does not include the taxed amount.

Example:
0.96
amount_incl_tax
number

The total discount amount including taxes

Example:
0.98
currency
string

The order currency

Example:
EUR
payment_info
string

The type of the event

Enumeration:
NOT PAID - TO BE PAID IN CASH

No wallet funds used

PAID BY CARD *******<last_4_card_digits>

No wallet funds used

FAILED TO BE PAID BY CARD

No wallet funds used

PARTIALLY PAID WITH WALLET FUNDS. AMOUNT DUE TO BE PAID IN CASH

Partially paid using wallet funds and another payment method

PARTIALLY PAID WITH WALLET FUNDS. AMOUNT DUE PAID BY CARD *******<last_4_card_digits>

Partially paid using wallet funds and another payment method

FULLY PAID WITH WALLET FUNDS

Fully paid using wallet funds

Example:
NOT PAID - TO BE PAID IN CASH
is_favorite
boolean

Defines whether the order is a favorite one

Example:
true
number_of_items
integer

The total number of items for the order

Example:
6
contact
Object

Details about the contact who placed the order

id
string GUID

The contact identifier

Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
code
string

The contact code

Example:
1234
name
string

The contact name

Example:
John Doe
email_address
string

The contact’s email address

Example:
sue@mymail.com
phone_number
string

The contact phone number

country_code
string

The phone number country code

Example:
CYP
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
category
Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
cancellation_reason
Object

Details about the reason that cancelled the order

id
string GUID

The cancellation reason identifier

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
name
string

The cvancellation reason

Example:
Void by customer
fulfilled_by
Object
id
string GUID
Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
name
string
Example:
CRM Nicosia
phone
string

The phone of the organisation

address
Object

Information about the organisation’s location

id
string GUID

The location identifier

Example:
LOC123456234567345674567895678IK
name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
care_of
string

The care of information of the location

Example:
c/o Company
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
order_items
Array

May be dealt with in list order items??

Object
id
string GUID

The order item identifier

Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
notes
string

The order item notes

Example:
Lorem Ipsum
life_cycle_state
string

The order item state

Example:
PENDING_DELIVERY
quantity
integer

The order item (product) quantity (same as product.quantity)

Example:
1
product
Object

Information about the order product item

id
string GUID

The product identifier

Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
sku
string

The product SKU

Example:
SKU1234
name
string

The product name

Example:
Iced Latte
quantity
integer

The product quantity

Example:
2
tags
Array
Object
id
string

The tag identifier

Example:
80362b63-a576-3540-586b-0dc1f3ab3bfd
name
string

The name of the tag

Example:
Coffees
colour
string

The colour of the tag

price
number

The unit price as defined in the order’s Invoice,excluding taxed amount

Example:
1.7
tax_amount
number

The applied tax amount

discount
Object
amount
number
amount_incl_tax
number
percentage
number
cost_before_discount
number

The sub-total of the order item before applying a discount. Tax amount is included.

cost
number

The order item’s sub-total. The sub-total includes the discount amount i.e. the discount is deducted from the product’s price

Example:
3.4
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
is_stockable
boolean
components
Array
Object
id
string GUID

The product component identifier

Example:
1866a75f-953e-4109-86b4-1cab53fbaaa8
sku
string

The product component SKU

Example:
B1234
name
string

The product component name

Example:
Brown Sugar
quantity
integer

The product component quantity

Example:
1
tags
Array
Object
id
string

The tag identifier

Example:
9c134cf3-c274-ee73-4921-01fb34033d4c
name
string

The name of the tag

Example:
Condiment
colour
string

The colour of the tag

price
number

The product component price (of a single unit)

Example:
0.5
net
number
tax
number
discount
number
total
number
variant_attributes
Array
Object
key
string
Example:
size
name
string
Example:
Size
value
string
Example:
Grande
price_terms
Object

Defines the termed period

billing_period
Object
duration
integer
uot
string
auto_renew
boolean
termed_period_cycles
integer
contract_period
Object
duration
integer
uot
string
trial_period
Object
duration
string
uot
string
price_model
string
Enumeration:
FIXED
VARIABLE
bill_model
string
Enumeration:
PRE_BILL
POST_BILL
external_reference
string

A reference identifier (usually an id) provided by an external system that provisioned this order

Example:
23423423234234
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
key_dates
Object
submitted_on
integer
Example:
1592809457
completed_on
integer
Example:
1592809457
cancelled_on
integer
Example:
1592809457
estimated_fulfillment_in
integer
Example:
30
estimated_fulfillment_UOT
string
Example:
MINUTES
estimated_fulfillment
integer epoch
Example:
1592809457
expires_on
integer epoch
Example:
1592809457
started_on
integer epoch
requested_date
integer epoch
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
available_for_printing
boolean

Defines whether the orders are configured to be printed

Example:
true
is_printed
boolean

Defines whether the order has been printed successfully

Example:
true
order_provision
Object

Details about order provision

available_for_provision
boolean

Defines whether the order is configured to be provisioned

Example:
true
is_provisioned
boolean

Defines whether the order has been provisioned successfully (applicable only if the order is available for provision)

Example:
false
provisioner
string

Defines the integration on which the order has been provisioned (applicable only if the order is available for provision)

Enumeration:
TWINSOFT
ALOHA
invoice
Object

This relates to the final invoice logged for the order

id
string
number
string
ref_number
string
queue
Object
id
string
name
string
statuses
Array
Object
id
string
name
string
date_achieved
integer epoch
colour
string
point_of_no_return
boolean
comment
string
external_reference
string

A reference provided by external systems

Example:
REF1234
payment_method
Object
type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
details
Object

The type of the event

id
string

The unique identifier of the contact’s payment method

identifier
string

A short description of the payment method. Depending on the payment method’s type different informaiton is returned:

  • Card: the brand, followed by the last 4 digits of the card plus expiration month/year
  • Account debit: Name: Bank code followed by the first 5 and the last 9 digits of the account number/IBAN
  • Wallet: Name: Email and/or phone used on registration
Example:
Visa *****1234
ad_hoc_discount
Object

The ad-hoc discount that is applied on the order’s total amount.This disocunt amount does not incldue discounts applied via Promotions

amount
number

The provided ad-hoc discount amount. The amount is tax inclusive

Example:
9.99
type
string

Discount is an amount or a percentage of the order’s total cost

Enumeration:
AMOUNT
PERCENTAGE
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
account_credit
number

Amount used from the account to pay off the order. Applicable only when account was in credit at the time of placing the order and it was used to pay off an order’s amount.

Example:
0.99
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8", 
    "number": "ORDER1234",
    "life_cycle_state": "IN_PROGRESS",
    "notes": "Lorem Ipsum",
    "number_of_milestones": 1,
    "supply_method": "DELIVERY",
    "total_cost": 5.99,
    "wallet_funds_amount": 1.98,
    "total_before_discount": 1,
    "amount_due": 3.01,
    "amount_to_collect": 1,
    "discount": {
        "amount": 0.96,
        "amount_incl_tax": 0.98
    },
    "currency": "EUR",
    "payment_info": "NOT PAID - TO BE PAID IN CASH",
    "is_favorite": true,
    "number_of_items": 6,
    "contact": {
        "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
        "code": "1234",
        "name": "John Doe",
        "email_address": "sue@mymail.com",
        "phone_number": "",
        "country_code": "CYP"
    },
    "address": {
        "address_line_1": "Elia Papakyriakou",
        "address_line_2": "7 Tower Stars",
        "state_province_county": "Egkomi",
        "town_city": "Nicosia",
        "postal_code": "2015",
        "country": "CYP",
        "lat": 35.157115,
        "lon": 33.313719,
        "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
    },
    "category": {
        "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
        "name": "Delivery Purchase"
    },
    "cancellation_reason": {
        "id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
        "name": "Void by customer"
    },
    "fulfilled_by": {
        "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
        "name": "CRM Nicosia",
        "phone": "",
        "address": {
            "id": "LOC123456234567345674567895678IK",
            "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",
            "care_of": "c/o Company",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    },
    "order_items": [
        {
            "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
            "notes": "Lorem Ipsum",
            "life_cycle_state": "PENDING_DELIVERY",
            "quantity": 1,
            "product": {
                "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
                "sku": "SKU1234",
                "name": "Iced Latte",
                "quantity": 2,
                "tags": [
                    {
                        "id": "80362b63-a576-3540-586b-0dc1f3ab3bfd",
                        "name": "Coffees",
                        "colour": ""
                    }
                ],
                "price": 1.7,
                "tax_amount": 1,
                "discount": {
                    "amount": 1,
                    "amount_incl_tax": 1,
                    "percentage": 1
                },
                "cost_before_discount": 1,
                "cost": 3.4,
                "classification": "TRACEABLE_PHYSICAL_GOOD",
                "is_stockable": true,
                "components": [
                    {
                        "id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
                        "sku": "B1234",
                        "name": "Brown Sugar",
                        "quantity": 1,
                        "tags": [
                            {
                                "id": "9c134cf3-c274-ee73-4921-01fb34033d4c",
                                "name": "Condiment",
                                "colour": ""
                            }
                        ],
                        "price": 0.5,
                        "net": 1,
                        "tax": 1,
                        "discount": 1,
                        "total": 1
                    }
                ],
                "variant_attributes": [
                    {
                        "key": "size",
                        "name": "Size",
                        "value": "Grande"
                    }
                ],
                "price_terms": {
                    "billing_period": {
                        "duration": 1,
                        "uot": ""
                    },
                    "auto_renew": true,
                    "termed_period_cycles": 1,
                    "contract_period": {
                        "duration": 1,
                        "uot": ""
                    },
                    "trial_period": {
                        "duration": "",
                        "uot": ""
                    },
                    "price_model": "VARIABLE",
                    "bill_model": "POST_BILL",
                    "external_reference": "23423423234234"
                },
                "creatives": [
                    {
                        "id": "CA123456789AQWSXZAQWS1236547896541",
                        "usage_type": "GOOGLE_LOGO_IMAGE",
                        "width": 2159,
                        "height": 3075,
                        "format": "jpg",
                        "url": "https://assets.crm.com/image/logo.jpg",
                        "public_id": "crm-com/image",
                        "media": [
                            {
                                "width": 200,
                                "height": 300,
                                "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "key_dates": {
        "submitted_on": 1592809457,
        "completed_on": 1592809457,
        "cancelled_on": 1592809457,
        "estimated_fulfillment_in": 30,
        "estimated_fulfillment_UOT": "MINUTES",
        "estimated_fulfillment": 1592809457,
        "expires_on": 1592809457,
        "started_on": 1,
        "requested_date": 1
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "available_for_printing": "true",
    "is_printed": true,
    "order_provision": {
        "available_for_provision": "true",
        "is_provisioned": "false",
        "provisioner": "ALOHA"
    },
    "invoice": {
        "id": "",
        "number": "",
        "ref_number": ""
    },
    "queue": {
        "id": "",
        "name": ""
    },
    "statuses": [
        {
            "id": "",
            "name": "",
            "date_achieved": 1,
            "colour": "",
            "point_of_no_return": true,
            "comment": ""
        }
    ],
    "external_reference": "REF1234",
    "payment_method": {
        "type": "CASH",
        "details": {
            "id": "",
            "identifier": "Visa *****1234"
        }
    },
    "ad_hoc_discount": {
        "amount": 9.99,
        "type": "AMOUNT"
    },
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    }
}
Perform Order Actions
PUT /orders/{id}/actions

Updates a single order based on the preferred action.

Path variables

id
string GUID required

The order (identifier) that will be updated

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The action that will be applied on the order

Enumeration:
START_PROGRESS
PAUSE

roadmap

RESUME

roadmap

COMPLETE
CANCEL
MARK_FAVORITE

roadmap

PRINT_ORDER

Print an order for preparation of order at a venue.

ORDER_PROVISION

Provision an order to a POS

CLONE

Clones the Order and use it as a template to easily create a new one

cancellation_reason_id
string GUID nullable

The reason why an order is cancelled (applicable if action = CANCEL)

Example:
caf332bc-4e90-47b5-a05d-142b264897b9
is_favorite
boolean nullable

Defines whether the order is a customer’s favourite one

Example:
true
provisioner
string nullable

Defines the integration on which the order has been provisioned (applicable only if the order is available for provision)

Enumeration:
TWINSOFT
ALOHA
contact_id
string
Examples

Responses

200 OK
Body
Object
id
string GUID

The order (identifier) that was updated

Example:
997f1287-3d83-827a-7199-e5df2c0e4e67
approval_requests
Array

Determines whether approval reuqests are applied or not, if not null an approval is requested

Object
id
string GUID

The apporval request identifier

Example:
3a4aad81-e5c2-72b7-3a86-903239d08767
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Start Order Progress
Complete Order
Cancel Order
PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "action": "START_PROGRESS"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}

PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "action": "COMPLETE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}
PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "action": "CANCEL",
    "cancellation_reason_id": "86d3a62b-5ee5-3a9e-b6dd-517a5dc908dd"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}
Order Items

All API’s concerned with order items after initial creation

GET /orders/{id}/items
List Order Items
GET /orders/{id}/items

Path variables

id
string required

Responses

200 OK
Body
Object
content
Array
Object
id
string
quantity
integer

How many items were ordered

Example:
10
delivered
integer

How many items were delivered (stocked out from business warehouse)

Example:
5
invoiced
integer

How many items are already invoiced.

Example:
3
notes
string
price
number
tax_amount
number
product
Object
id
string
sku
string
name
string
measurement_unit
string
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
devices
Array

List of strings of device serial numbers

Object
serial_number
string
dispatched
boolean
Example 1
GET https://sandbox.crm.com/backoffice/v1/orders/{id}/items HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "quantity": 10,
            "delivered": 5,
            "invoiced": 1,
            "notes": "",
            "price": 1,
            "tax_amount": 1,
            "product": {
                "id": "",
                "sku": "",
                "name": "",
                "measurement_unit": "",
                "classification": "TRACEABLE_PHYSICAL_GOOD"
            },
            "devices": [
                {
                    "serial_number": "",
                    "dispatched": true
                }
            ]
        }
    ]
}
Order Milestones

All API’s concerned with order specific milestones after creation

GET /orders/{id}/milestones
PUT /orders/{id}/milestones
DELETE /orders/{id}/milestones/{milestone_id}
List Order Milestones
GET /orders/{id}/milestones

Lists the order specific milestones configured during the ordering process.

Path variables

id
string required

Responses

200 OK
Body
Array
Object
id
string
date_achieved
string
percentage
number

The order milestone percentage.

status
Object
id
string
name
string
colour
string
invoice
Object
id
string
number
string
amount
number
Example 1
GET https://sandbox.crm.com/backoffice/v1/orders/{id}/milestones HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "date_achieved": "",
        "percentage": 1,
        "status": {
            "id": "",
            "name": "",
            "colour": ""
        },
        "invoice": {
            "id": "",
            "number": ""
        }
    }
]
Update Order Milestones
PUT /orders/{id}/milestones

Updates the order specific milestones that were set in order creation. This will be performed as part of the order update flow.

Path variables

id
string required

Request body

Array
Object
status_id
string
percentage
number

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/orders/{id}/milestones HTTP/1.1 

Content-Type: application/json

[
    {
        "status_id": "",
        "percentage": 1,
        "date": 1
    }
]

HTTP/1.1 200 OK 
Delete Order Milestone
DELETE /orders/{id}/milestones/{milestone_id}

Deletes an order milestone set up during the initial order flow.

Path variables

id
string required
milestone_id
string required

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/orders/{id}/milestones/{milestone_id} HTTP/1.1 

HTTP/1.1 204 No Content 
Attachements
POST /orders/{id}/files
DELETE /orders/{id}/files/{file_id}
GET /orders/{id}/files
Add Order Attachement File
POST /orders/{id}/files

Connect an uploaded file to an existing order

Path variables

id
string GUID required

The order (identifier) that file will be attached

Example:
66451204-4404-894c-4dc6-486c540ece40

Notes

FILE UPLOAD FLOW

Integrating file upload for Orders should be based on the following APIs

  1. Upload File Signature
  2. Connect a file to an Order

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required nullable

The file (identifier) to be attached

Example:
30526723-24a3-e4e3-1a75-b26b1b41f05c
url
string required nullable

URL of the file to be attached

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
description
string nullable

The file description

Example:
Screenshot sent by customer

Responses

200 OK
Body
Object
id
string GUID

The service request identifier

Example:
66451204-4404-894c-4dc6-486c540ece40
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/orders/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

Content-Type: application/json

{
    "file_id": "30526723-24a3-e4e3-1a75-b26b1b41f05c",
    "url": "https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug",
    "description": "Screenshot sent by customer"
}
Delete Order Attachement
DELETE /orders/{id}/files/{file_id}

Delete a specific order attachment file

Path variables

id
string GUID required

The order (identifier) that file will be deleted

Example:
66451204-4404-894c-4dc6-486c540ece40
file_id
string GUID required

The attachment file (identifier) that will be deleted

Example:
04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/orders/66451204-4404-894c-4dc6-486c540ece40/files/04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Order Attachements
GET /orders/{id}/files

Retrieve all attachment files for a specific order

Path variables

id
string GUID required

The order (identifier) that files will be retrieved

Example:
66451204-4404-894c-4dc6-486c540ece40

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The attachment identifier

Example:
3ae9d64a-8a3b-f1e1-eed6-05b307f926fb
mime
string

The mime type of the uploaded file

Enumeration:
csv
doc
docx
xls
xlsx
pdf
log
txt
png
jpg
jpeg
svg
description
string

The attachement description

Example:
Screenshot sent by customer
file
Object

The attachement file details

id
string GUID

The file identifier

Example:
0317868f-28f8-9f56-d248-5a78718b38cc
url
string

The file URL endpoint

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
name
string

The file name

Example:
img.png
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/orders/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
            "mime": "png",
            "description": "this is a brief description of this image",
            "file": {
                "id": "0317868f-28f8-9f56-d248-5a78718b38cc",
                "name": "img.png"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Payment Intents
POST /payment_intents
PUT /payment_intents/{id}/actions
GET /payment_intents
GET /payment_intents/{id}
Create Payment Intent
POST /payment_intents

Creates a new payment intent

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string
organisation_id
string
payment_method_id
string required

The contact’s payment method that will be used for the payment. If a payment method is not specified, then the contact’s primary payment method will be selected

Example:
2ac0809f-ed91-4b68-b912-5bd6064d901e
amount
number required

The amount intended to be retrieved from the customer’s payment method

Example:
9.99
currency_code
string required

The payment intent’s currency. If not specified, then the currency of the contact’s primary account will be autommatically used.

Example:
EUR
confirm
boolean

Payment intent is created and confirmed in one go. Applicable when customers have already opt in to automatic payments using their registered payment methods

Default:
true
Example:
true
capture
string required
Enumeration:
ON_HOLD
Default:
ON_HOLD
statement
string
description
string
entity
Object
id
string
type
string
Enumeration:
INVOICE
ORDERS
PAYMENTS
period
Object

Payment Intent’s billing period. Applicable only when recurring billing process submits intents to collect money. The period indirectly shows that the intent was created because of Billing Run

from
integer

The date from which a subscription is billed

Example:
1654698334
to
integer

The date until which a subscription is billed

Example:
1657290334

Responses

201 Created
Body
Object
id
string

The unique identifier of the payment intent

client_secret
string

A unique key for the payment intent that should be used by front-end processes to process the payment intent since these processes should not have access to the payment intent as such. The client secret cannot be used to modify the payment intent’s info such as the amount.

state
string
Enumeration:
REJECTED

Funds do not exist.

PENDING

Request sent to PG, it was successfully logged but there still no response if funds exists or not (JCC SEPA)

REQUIRES_CAPTURING

Request sent to PG, money successully put on hold. THE PG waits for CRM side to capture the money

error_code
string
error_description
string
Example 1
POST https://sandbox.crm.com/backoffice/v1/payment_intents HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "",
    "organisation_id": "",
    "payment_method_id": "2ac0809f-ed91-4b68-b912-5bd6064d901e",
    "amount": 9.99,
    "currency_code": "EUR",
    "confirm": "true",
    "capture": "ON_HOLD",
    "statement": "",
    "description": "",
    "entity": {
        "id": "",
        "type": "PAYMENTS"
    },
    "period": {
        "from": 1,
        "to": 1
    }
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "",
    "client_secret": "",
    "state": "REQUIRES_CAPTURING",
    "error_code": "",
    "error_description": ""
}
Perform Payment Intent Actions
PUT /payment_intents/{id}/actions

Updates an existing Payment intent. A Payent intent can only be updated while it’s in Pending or Requires Capturing processing states

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

Change the intent’s state

Enumeration:
CONFIRM

Applicable only if the intent was not confirmed on its creation

REJECT

JCC used for pluign callbacks

COMPLETE

JCC used for pluign callbacks

Example:
CAPTURE
entity
Object
type
string

The type of the event

Enumeration:
INVOICE
TOPUP
ORDER
Example:
ORDER
id
string

Responses

200 OK
Body
Object
id
string

The unique identifier of the payment intent

client_secret
string

A unique key for the payment intent that should be used by front-end processes to process the payment intent since these processes should not have access to the payment intent as such. The client secret cannot modify the payetn intent’s info.

state
string

The type of the event

Enumeration:
REQUIRES_CAPTURING
REJECTED
COMPLETED
PENDING
CANCELLED
Example:
REQUIRES_CAPTURING
error_code
string
error_description
string
Example 1
PUT https://sandbox.crm.com/backoffice/v1/payment_intents/{id}/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "CAPTURE",
    "entity": {
        "type": "ORDER",
        "id": ""
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "client_secret": "",
    "state": "ORDER",
    "error_code": "",
    "error_description": ""
}
List Payment Intents
GET /payment_intents

List all payment intents submitted for a customer

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
entity
string optional
Enumeration:
INVOICE
TOPUP
ORDER
Example:
ORDER
entity_id
string optional
created_date
string optional
client_secret
string optional
contact_id
string optional

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
amount
number
currency
string
payment_method
Object

The type of the event

id
string

The unique identifier of the contact’s payment method

identifier
string

A short description of the payment method. Depending on the payment method’s type different informaiton is returned:

  • Card: the brand, followed by the last 4 digits of the card plus expiration month/year
  • Account debit: Name: Bank code followed by the first 5 and the last 9 digits of the account number/IBAN
  • Wallet: Name: Email and/or phone used on registration
Example:
Visa *****1234
created_date
string
state
string

The type of the event

Enumeration:
REQUIRES_CAPTURING
REJECTED
COMPLETED
PENDING
CANCELLED
Example:
REQUIRES_CAPTURING
entity
Object
id
string
number
string
type
string

The type of the event

Enumeration:
INVOICE
TOPUP
ORDER
Example:
ORDER
period
Object

Payment Intent’s billing period. Applicable only when recurring billing process submits intents to collect money. The period indirectly shows that the intent was created because of Billing Run

from
integer

The date from which a subscription is billed

Example:
1654698334
to
integer

The date until which a subscription is billed

Example:
1657290334
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/payment_intents HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "amount": 1,
            "currency": "",
            "payment_method": {
                "id": "",
                "identifier": "Visa *****1234"
            },
            "created_date": "",
            "state": "REQUIRES_CAPTURING",
            "entity": {
                "id": "",
                "number": "",
                "type": "ORDER"
            },
            "period": {
                "from": 1654698334,
                "to": 1657290334
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Payment Intent
GET /payment_intents/{id}

Retrieves detailed information for a payment intent

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
amount
number
currency
string
payment_method_type
string

The type of the event

Enumeration:
CARD

Credit/Debit/Prepaid cards

WALLET

Wallet related to either a card, bank account or has a monetary value

ACCOUNT_DEBIT

Collect money directly from an account

Example:
CARD
capture
string
Enumeration:
ON_HOLD
client_secret
string
payment_method
Object
id
string
card
Object

The card’s main information. Required and applicable if the payment method type is CARD

name
string

The card’s name

Example:
Default Card
brand
string

The card’s brand

Example:
VISA
funding_type
string

The type of the event

Enumeration:
CREDIT
DEBIT
PREPAID
Example:
CREDIT
first6
string

The first 6 digits of the card. Either the card number or the first 6 and last 4 digits must be specified

last4
string

The last 4 digits f the card. Either the card number or the first 6 and last 4 digits must be specified

expiration_month
integer

The card expiration month

Example:
1
expiration_year
integer

The card expiration year

Example:
2020
country_of_issue
string

The card issue country (3 char country code)

Example:
CYP
cvc
string
card_holder_details
Object

Information about the card holder

card_holder_name
string

The name of the card holder

Example:
John Doe
address_line_1
string

The address related to the card

Example:
Elia Papakyriakou
address_line_2
string

Additional address information related to the card

Example:
7 Tower Star
address_city
string

The city related to the card

Example:
Nicosia
address_zip
string

The zip code related to the card

Example:
2415
address_state
string

The state related to the card

Example:
Nicosia
address_country
string

The country related to the card

Example:
CYP
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
account_debit
Object

The bank details.Required and applicable if the payment method is set to BANK

account_name
string
account_number
string nullable

The bank account number.

Example:
001002001
iban
string required nullable

The IBAN code.

Example:
0143240434320434
bank
string nullable

The name of the customer’s bank

Example:
Barclays
bank_code
string nullable

Institution number of the customer’s bank.

Example:
0032933-1123
branch
string nullable

The identifier of the bank branch

Example:
Ascot
swift
string nullable

The bank account swift number

Example:
12345678
sort_code
string nullable

The sort code

Example:
20-02-53
mandate
Object
reference
string
type
string

The mandate (sequence) type

Enumeration:
FIRST
RECURRING
FINAL
ONEOFF
sign_date
integer epoch
Example:
1654756878
termination_date
integer epoch
Example:
1654756887
account_type
string

The type of the event

Enumeration:
SAVINGS
CHECKING
BUSINESS_CHECKING
Example:
SAVINGS
integration_id
string

The payment gateway’s integration identifier

account_holder_details
Object
account_holder_name
string
address_line_1
string
address_line_2
string
address_state
string
address_city
string
address_zip
string
address_coutry
string
use_billing_address
boolean
country
string

The country the bank account is located in.

Example:
CY
currency
string
Example:
EUR
wallet
Object

The card’s main information. Required and applicable if the payment method type is CARD

email
string nullable

The email used when registering to the walled-based payment method

Example:
jsmith@email.com
phone
Object nullable

The phone used when registering to the walled-based payment method

name
string
country_code
string
number
string
msisdn
string
gateway_token
Array
Object
token
string
gateway
string nullable
Enumeration:
JCC
JCC_MERCHANT
SETTLE
integration
Object nullable
id
string
name
string
state
string

The type of the event

Enumeration:
REQUIRES_CAPTURING
REJECTED
COMPLETED
PENDING
CANCELLED
Example:
REQUIRES_CAPTURING
entity
Object
type
string

The type of the event

Enumeration:
INVOICE
TOPUP
ORDER
Example:
ORDER
number
string
id
string
created_date
integer
cancelled_date
integer

Appicable only on cancelling the payment intent

failure_reason
string

Applicable only if funds failed to be collected (payment intent’s state is Rejected)

contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
period
Object

Payment Intent’s billing period. Applicable only when recurring billing process submits intents to collect money. The period indirectly shows that the intent was created because of Billing Run

from
integer

The date from which a subscription is billed

Example:
1654698334
to
integer

The date until which a subscription is billed

Example:
1657290334
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payment_intents/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "amount": 1,
    "currency": "",
    "payment_method_type": "CARD",
    "capture": "ON_HOLD",
    "client_secret": "",
    "payment_method": {
        "id": "",
        "card": {
            "name": "Default Card",
            "brand": "VISA",
            "funding_type": "CREDIT",
            "first6": "",
            "last4": "",
            "expiration_month": 1,
            "expiration_year": 2020,
            "country_of_issue": "CYP",
            "cvc": "",
            "card_holder_details": {
                "card_holder_name": "John Doe",
                "address_line_1": "Elia Papakyriakou",
                "address_line_2": "7 Tower Star",
                "address_city": "Nicosia",
                "address_zip": "2415",
                "address_state": "Nicosia",
                "address_country": "CYP"
            },
            "gateway_token": [
                {
                    "token": "",
                    "gateway": "SETTLE",
                    "integration": {
                        "id": "",
                        "name": ""
                    }
                }
            ]
        },
        "account_debit": {
            "account_name": "",
            "account_number": "001002001",
            "iban": "0143240434320434",
            "bank": "Barclays",
            "bank_code": "0032933-1123",
            "branch": "Ascot",
            "swift": "12345678",
            "sort_code": "20-02-53",
            "mandate": {
                "reference": "",
                "sign_date": 1
            },
            "account_type": "SAVINGS",
            "integration_id": "",
            "account_holder_details": {
                "account_holder_name": "",
                "address_line_1": "",
                "address_line_2": "",
                "address_state": "",
                "address_city": "",
                "address_zip": "",
                "address_coutry": "",
                "use_billing_address": true
            },
            "country": "CY",
            "currency": "EUR"
        },
        "wallet": {
            "email": "jsmith@email.com",
            "phone": {
                "name": "",
                "country_code": "",
                "number": "",
                "msisdn": ""
            },
            "gateway_token": [
                {
                    "token": "",
                    "gateway": "JCC",
                    "integration": {
                        "id": "",
                        "name": ""
                    }
                }
            ]
        }
    },
    "state": "REQUIRES_CAPTURING",
    "entity": {
        "type": "ORDER",
        "number": "",
        "id": ""
    },
    "created_date": 1,
    "cancelled_date": 1,
    "failure_reason": "",
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    },
    "period": {
        "from": 1654698334,
        "to": 1657290334
    }
}
Passes
Pass Plans
POST /pass_plans
PUT /pass_plans/{id}
DELETE /pass_plans/{id}
GET /pass_plans
GET /pass_plans/{id}
POST /pass_plans/{id}/export
Create Pass Plan
POST /pass_plans

Create a pass plan

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the pass plan

Example:
EUR10-50 TOP-UP ELECTRONIC
description
string

A description of the pass plan

Example:
10-50EUR Top-up passes in electronic format
classification
string required

The classification of the pass plan

Enumeration:
PROMOTION
GIFT
TOPUP
life_cycle_state
string

The life cycle state of the pass plan

Enumeration:
ACTIVE

Pass plan can be used and passes can be generated

INACTIVE

Pass plan not in use

Default:
INACTIVE
promotion_id
string GUID nullable

The promotion that the promotion pass will consume. Only applicable for classification PROMOTION. In such cases, either a Promotion OR a Reward Offer must be specified

Example:
4AD9C84FA60F9FE407140E20F707726A
reward_offer_id
string GUID nullable

The reward offer that the promotion pass will consume. Only applicable for classification PROMOTION. In such cases, either a Promotion OR a Reward Offer must be specified

Example:
4AD9C84FA60F9FE407140E20F707726A
distribution_method
string

The distribution method of the Passes to be created (i.e. type of pass codes). Applicable only for PROMOTION

Enumeration:
MULTIPLE

Multiple unique codes

SINGLE

Single code for all passes

maximum_usage
integer

The maximum number of times the pass can be used, 1 = single use pass >1 = multiple uses (for PROMOTION passes)

validity
Object

The validity of the passes - this relates to the date whereby the pass can be redeemed by

type
string

The validity type

Enumeration:
PERIOD

Pass is valid for a period of time

DATE

Pass is valid for a specific date

period
integer

The validity period, applicable if validity type = PERIOD (i.e. expires in X days/months/years)

Example:
1
uot
string

The UOT of the period, applicable if validaity type = PERIOD

Enumeration:
DAY
MONTH
YEAR
to_date
integer epoch

The ‘valid until’ date in case of DATE type

Example:
1591703675
value
Object

The value of the pass in case of GIFT and TOPUP

type
string

Are passes of fixed or variable value? FIXED indicates that the pass value is predefined, VARIABLE allows the value of the pass to be set during creation (within a range)

Enumeration:
FIXED
VARIABLE
fixed_amount
number

The fixed value amount

Example:
100
minimum
number

The minimum allowed value of the pass for VARIABLE value passes

Example:
10
maximum
number

The maximum allowed value of the pass for VARIABLE value passes

Example:
50
printed
boolean

Defines whether the passes will be printed (true=PRINTED, false=ELECTRONIC)

Example:
false
code_format
Object

Definition of the pass code format to be followed when a pass code is being created

type
string

The type of the code format, if distribution_method = MULTIPLE

Enumeration:
ALPHANUMERIC
ALPHABETIC
NUMERIC
prefix
string

The prefix of the code if distribution_method = MULTIPLE

Example:
ABC
suffix
string

The suffix of the code if distribution_method = MULTIPLE

Example:
2020
length
integer

The length of the code if distribution_method = MULTIPLE (min.7, max.16)

Example:
10
pin_required
boolean

Defines whether a generated pass will be associated with a pin

Default:
false
Example:
true
code
string

The user defined single pass code (applicable only if distribution_method is SINGLE)

Example:
123456
spend_condition_id
string

GUID of spend group if spend_option = COMMERCE

Example:
99869C84FA60F9FE407140E20F707726A
spend_option
string

Which wallet balance will the pass credit upon redemption? For TOPUP and GIFT passes

Enumeration:
OPEN

Can be spent without restrictions

COMMERCE

Spend conditions could apply

number_of_passes
integer

For PRINTED passes this is the number of passes to generate, for ELECTRONIC passes this is the maximum number of passes to be generated (0=unlimited)

custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the created pass plan

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/pass_plans HTTP/1.1 

Content-Type: application/json

{
    "name": "EUR10-50 TOP-UP ELECTRONIC",
    "description": "10-50EUR Top-up passes in electronic format",
    "classification": "TOPUP",
    "life_cycle_state": "INACTIVE",
    "promotion_id": "4AD9C84FA60F9FE407140E20F707726A",
    "reward_offer_id": "4AD9C84FA60F9FE407140E20F707726A",
    "distribution_method": "MULTIPLE",
    "maximum_usage": 1,
    "validity": {
        "type": "DATE",
        "period": 1,
        "uot": "DAY",
        "to_date": 1591703675
    },
    "value": {
        "type": "VARIABLE",
        "fixed_amount": 100,
        "minimum": 10,
        "maximum": 50
    },
    "printed": "false",
    "code_format": {
        "type": "NUMERIC",
        "prefix": "ABC",
        "suffix": "2020",
        "length": 10,
        "pin_required": true,
        "code": "123456"
    },
    "spend_condition_id": "99869C84FA60F9FE407140E20F707726A",
    "spend_option": "COMMERCE",
    "number_of_passes": 1,
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update Pass Plan
PUT /pass_plans/{id}

Update specific details of a pass plan.

A pass plan can only be updated if none of it’s passes have been generated yet

Path variables

id
string GUID required

The ID of the pass plan to be updated

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string

The life cycle state of the pass plan

Enumeration:
ACTIVE

Pass plan can be used and passes can be generated

INACTIVE

Pass plan not in use

name
string

The name of the pass plan

Example:
Xmas Gift Cards
description
string

A description of the pass plan

Example:
Gift Cards for Christmas
maximum_usage
integer

The maximum number of times the pass can be used, 1 = single use pass, >1 = multiple uses (for PROMOTION passes)

Example:
1
validity
Object

The validity of the passes - this relates to the date whereby the pass can be redeemed by

type
string

Pass plan validity type

Enumeration:
PERIOD

Pass is valid for a period of time

DATE

Pass is valid for a specific date

ALWAYS

Pass is always valid (never expires)

period
integer

The validity period, applicable if validity type = PERIOD (i.e. expires in X days/months/years)

Example:
1
uot
string

The UOT of the period, applicable if validaity type = PERIOD

Enumeration:
DAY
MONTH
YEAR
to_date
integer epoch

The ‘valid until’ date in case of DATE type

Example:
1591703675
printed
boolean

Defines whether the passes will be printed (true=printed, false=electronic)

Example:
true
spend_option
string

Which wallet balance will the pass credit upon redemption? For TOPUP and GIFT passes

Enumeration:
OPEN

Can be spent without restrictions

COMMERCE

Spend conditions may apply

code_format
Object

Definition of the pass code format to be followed when a pass code is being created

type
string

The type of the code format if distribution_method = MULTIPLE

Enumeration:
ALPHANUMERIC
ALPHABETIC
NUMERIC
prefix
string

The prefix of the code if distribution_method = MULTIPLE

Example:
ABC
suffix
string

The suffix of the code if distribution_method = MULTIPLE

Example:
YZ
length
integer

The length of the code if distribution_method = MULTIPLE (min.7, max.16)

Example:
10
pin_required
boolean

Defines whether generated passes require an associated pin

Example:
true
code
string

The user defined single pass code (applicable only if distribution_method is SINGLE)

Example:
123456
number_of_passes
integer

For PRINTED passes this is the number of passes to generate, for ELECTRONIC passes this is the maximum number of passes to be generated (0=unlimited)

spend_condition_id
string

GUID of spend group if spend_option = COMMERCE

Example:
99869C84FA60F9FE407140E20F707726A
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the pass plan updated

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/pass_plans/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "INACTIVE",
    "name": "Xmas Gift Cards",
    "description": "Gift Cards for Christmas",
    "maximum_usage": 1,
    "validity": {
        "type": "PERIOD",
        "period": 1,
        "uot": "DAY",
        "to_date": 1591703675
    },
    "printed": "true",
    "spend_option": "COMMERCE",
    "code_format": {
        "type": "ALPHABETIC",
        "prefix": "ABC",
        "suffix": "YZ",
        "length": 10,
        "pin_required": true,
        "code": "123456"
    },
    "number_of_passes": 1,
    "spend_condition_id": "99869C84FA60F9FE407140E20F707726A",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Delete Pass Plan
DELETE /pass_plans/{id}

Delete an existing pass plan.

A pass plan can opnly be deleted if none of it’s passes have been generated yet

Path variables

id
string GUID required

The pass plan identifier to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/pass_plans/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 
List Pass Plans
GET /pass_plans

List all the available pass plans

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
search_value
string optional

Search pass plans using a name

Example:
Xmas
classification
string optional

Search pass plans using a classification

Enumeration:
GIFT
TOPUP
PROMOTION
life_cycle_state
string optional

Search passs plans using life cycle state

Enumeration:
ACTIVE

Pass plan can be used and passes can be generated

INACTIVE

Not in use

distribution_method
string optional

Search pass plans using the distribution method

Enumeration:
MULTIPLE

Multiple unique values

SINGLE

Single code for all passes

printed
boolean optional

Defines whether the passes will be printed (true=PRINTED, false=ELECTRONIC)

Example:
true
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The GUID of the pass plan

Example:
40E20F707726A4AD9C84FA60F9FE4071
life_cycle_state
string

The life cycle state of the pass plan

Enumeration:
ACTIVE

Pass plan can be used and passes can be generated

INACTIVE

Not in use

name
string

The name of the pass plan

Example:
Xmas Gift Cards
description
string

The description of the pass plan

Example:
Gift Cards for Christmas
classification
string

The classification of the pass type

Enumeration:
GIFT
TOPUP
PROMOTION
distribution_method
string

The distribution method of passes (i.e. type of pass codes). Applicable only for PROMOTION

Enumeration:
MULTIPLE

Multiple unique values

SINGLE

Single code for all passes

printed
boolean

Defines whether the passes will be printed (true=PRINTED, false=ELECTRONIC)

Example:
false
number_of_passes
integer

For PRINTED passes this is the number of passes to generate, for ELECTRONIC passes this is the maximum number of passes to be generated (0=unlimited)

Example:
1542
passes_generated
integer

Number of passes generated either PRINTED or ELECTRONIC

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/pass_plans HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "40E20F707726A4AD9C84FA60F9FE4071",
            "life_cycle_state": "ACTIVE",
            "name": "Xmas Gift Cards",
            "description": "Gift Cards for Christmas",
            "classification": "PROMOTION",
            "distribution_method": "SINGLE",
            "printed": "false",
            "number_of_passes": 1542,
            "passes_generated": 1
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Pass Plan
GET /pass_plans/{id}

Retrieves details for an existing pass plan

Path variables

id
string GUID required

The ID of the pass plan to be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
life_cycle_state
string

The life cycle state of the pass plan

Enumeration:
ACTIVE

Pass plan can be used and passes can be generated

INACTIVE

Not in use

name
string

The name of the pass type

Example:
Xmas Gift Cards
description
string

The description of the pass type

Example:
Gift Cards for Christmas
classification
string

The classification of the pass type

Enumeration:
GIFT
TOPUP
PROMOTION
promotion
Object

The promotion that the passes will consume (only for PROMOTION type pass plans)

id
string GUID

The ID of the promotion

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the promotion

Example:
XMAS 50% off
reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
distribution_method
string

The distribution method of passes (i.e. type of pass codes). Applicable only for PROMOTION

Enumeration:
MULTIPLE

Multiple unique values

SINGLE

Single code for all passes

maximum_usage
integer

The maximum number of times the pass can be used, 1 = single use pass >1 = multiple uses (for PROMOTION passes)

validity
Object

The validity of the passes - this relates to the date whereby the pass can be redeemed by

type
string

Validity type

Enumeration:
PERIOD

Pass is valid for a period of time

DATE

Pass is valid for a specific date

ALWAYS

Pass is always valid (never expires)

period
integer

The validity period, applicable if validity type = PERIOD (i.e. expires in X days/months/years)

Example:
1
uot
string

The UOT of the period, applicable if validaity type = PERIOD

Enumeration:
DAY
MONTH
YEAR
to_date
integer epoch

The ‘valid until’ date in case of DATE type

Example:
1591703675
value
Object

The value of the pass in case of GIFT and TOPUP

type
string

Pass value type. FIXED indicates that the pass value is predefined, VARIABLE allows the value of the pass to be set during creation (within a range)

Enumeration:
FIXED

All passes have the same fixed value

VARIABLE

Passes can have variable values

fixed_amount
number

The fixed value amount

minimum
number

The minimum allowed value of the pass - for VARIABLE value passes

Example:
10
maximum
number

The maximum allowed value of the pass - for VARIABLE value passes

Example:
50
spend_option
string

The wallet balance which the pass will credit upon redemption. For TOPUP and GIFT passes

Enumeration:
OPEN

Can be spent without restrictions

COMMERCE

Spend conditions could apply

printed
boolean

Defines whether the passes will be printed (true=printed, false=electronic)

Example:
true
code_format
Object

Definition of the pass code format to be followed when a pass code is being created

type
string

The pass code format if usage method = MULTIPLE

Enumeration:
ALPHANUMERIC
ALPHABETIC
NUMERIC
prefix
string

The prefix of the code

Example:
ABC
suffix
string

The suffix of the code

Example:
YZ
length
integer

The length of the code (min.7, max 16)

Example:
10
pin_required
boolean

Defines whether generated passes require a associated pin

Example:
true
code
string

The user defined single pass code (applicable only if distribution method is SINGLE)

Example:
123456
number_of_passes
integer

For PRINTED passes this is the number of passes to generate, for ELECTRONIC passes this is the maximum number of passes to be generated (0=unlimited)

passes_generated
integer

Number of passes generated (for printed - this is the number of printed passes, for electronic - this is the number of passes generated so far)

spend_conditions
Object

Applicable spend conditions - if spend_option = COMMERCE

id
string

The spend condition ID

Example:
ANP9C84FA60F9FE407140E20F707726A
name
string

The spend condition name

Example:
Anywhere & Anytime
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/pass_plans/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "life_cycle_state": "INACTIVE",
    "name": "Xmas Gift Cards",
    "description": "Gift Cards for Christmas",
    "classification": "GIFT",
    "promotion": {
        "id": "4AD9C84FA60F9FE407140E20F707726A",
        "name": "XMAS 50% off"
    },
    "reward_offer": {
        "id": "c888dd7a-7476-538c-730a-9f924bd82d04",
        "name": "Birthday Offer"
    },
    "distribution_method": "MULTIPLE",
    "maximum_usage": 1,
    "validity": {
        "type": "DATE",
        "period": 1,
        "uot": "MONTH",
        "to_date": 1591703675
    },
    "value": {
        "type": "FIXED",
        "fixed_amount": 1,
        "minimum": 10,
        "maximum": 50
    },
    "spend_option": "COMMERCE",
    "printed": "true",
    "code_format": {
        "type": "ALPHANUMERIC",
        "prefix": "ABC",
        "suffix": "YZ",
        "length": 10,
        "pin_required": true,
        "code": "123456"
    },
    "number_of_passes": 1,
    "passes_generated": 1,
    "spend_conditions": {
        "id": "ANP9C84FA60F9FE407140E20F707726A",
        "name": "Anywhere & Anytime"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Export Passes
POST /pass_plans/{id}/export

Export the generated passes of a pass plan to a .csv file and send it to the logged in user’s email

Path variables

id
string GUID required

The id of the pass plan to export its generated passes

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/pass_plans/4AD9C84FA60F9FE407140E20F707726A/export HTTP/1.1 

HTTP/1.1 200 OK 
Passes
POST /passes/generate
PUT /passes/{id}
GET /passes
GET /passes/{id}
POST /passes
PUT /passes/{id}/actions
Create Pass
POST /passes/generate

Request to generate one or more passes:

  • For printed passes - generate all the passes for a pass plan
  • For electronic pass - generate a single pass for a customer (only via a third-party system request)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
pass_plan_id
string GUID required

The id of the pass plan for which a pass is to be generated

Example:
0F9FE407140E20F707726A4AD9C84FA6
pass_value
number

Set the value of the pass - applicable for pass plans configured for ‘variable’ value passes

Example:
50
recipient
Object

The recipient information. For Top-up passes this is the registered contact who will also be redeeming the pass. For Gift passes this is the registered/unregistered recipient who will be redeeming the pass.

name
string

The recipient name

Example:
John Smith
medium_type
string

The communication medium to be used to send the pass information. Note: For electronic Gift passes - if the registered_contact information has been provided then medium_type is not mandatory

Enumeration:
SMS
EMAIL
Example:
EMAIL
medium_value
string

The value of the communication medium to be used to send the pass information Note: For electronic Gift passes - if the registered_contact information has been provided then medium_value is not mandatory

Example:
j.smith@crm.com
country_code
string

Applicable for SMS

Example:
GRE
registered_contact
Object

Details requried if the pass is being created for a registered contact.

contact_id
string GUID nullable

Contact id of the existing Contact

Example:
acaae121-b4af-4663-8646-47bb541c971d
wallet_id
string GUID nullable

Wallet id of the existing contact

Example:
4613eb36-e5e8-46e8-9517-b1a31e86c89c
gift_sender
Object

Gift sender information (for electronic Gift passes only).

name
string required

Gift sender name

Example:
Kelly Smith
message
string

Gift sender message to accompany the gift pass

Example:
Happy birthday John, have a great day. Hope to see you soon. Kelly
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body

The response will only return pass details if a single electronic pass has been generated, if multiple printed passes have been generated then nothing is returned.

Object
id
string

The ID of the generated pass (if a single electronic pass was generated)

Example:
407140E20F707726A99869C84FA60F9FE
pass_code
string

The pass code (if a single electronic pass was generated)

pin
string

Pass PIN (if applicable, and if a single electronic pass was generated)

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/passes/generate HTTP/1.1 

Content-Type: application/json

{
    "pass_plan_id": "0F9FE407140E20F707726A4AD9C84FA6",
    "pass_value": 50,
    "recipient": {
        "name": "John Smith",
        "medium_type": "EMAIL",
        "medium_value": "j.smith@crm.com",
        "country_code": "GRE",
        "registered_contact": {
            "contact_id": "acaae121-b4af-4663-8646-47bb541c971d",
            "wallet_id": "4613eb36-e5e8-46e8-9517-b1a31e86c89c"
        }
    },
    "gift_sender": {
        "name": "Kelly Smith",
        "message": "Happy birthday John, have a great day. Hope to see you soon. Kelly"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Update Pass
PUT /passes/{id}

Update the life cycle state, the expiration date, the initial value or the pin of a single pass

Path variables

id
string required

The pass unique identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string nullable

The new state of the pass

Enumeration:
ACTIVE

Only passes in ‘Draft’ state can be activated

CANCELLED

Only passes in 'Draft or ‘Active’ state can be cancelled

expiration_date
integer epoch nullable

The new expiration date

Example:
1592919625
initial_load
number nullable

The value that the pass should be loaded with (applicable only for printed passes of variable value, and whose initial value is ‘null’)

Example:
50
pin
string nullable

PIN has a dual purpose:

  1. If simply updating the PIN, then provide the new 4-digit PIN value
  2. If cancelling a redeemed Gift Pass (life_cycle_state = CANCELLED, and the pass type is Gift Pass) then the pin must also be provided in order for cancellation to proceed
Example:
1908
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The update pass identifier

Example:
65bd03bf-b33e-469d-a8cf49
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/passes/{id} HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "life_cycle_state": "ACTIVE",
    "expiration_date": 1592919625,
    "initial_load": 50,
    "pin": "1908",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
List Passes
GET /passes

Returns a list of Passes based on request parameters

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
expiration_date
string optional

Filter based on the expiration date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. expiration_date[gte]=1618395497&expiration_date[lt]=1618395497).

Enumeration:
expiration_date[gt]

Returns results where the expiration date is greater than this value

expiration_date[gte]

Returns results where the expiration date is greater than or equal to this value

expiration_date[lt]

Returns results where the expiration date is less than this value

expiration_date[lte]

Returns results where the expiration date is less then or equal to this value

created_date
string optional

Filter based on the creation date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. created_date[gte]=1618395497&created_date[lt]=1618395497).

Enumeration:
created_on[gt]

Returns results where the created date is greater than this value

created_on[gte]

Returns results where the created date is greater than or equal to this value

created_on[lt]

Returns results where the created date is less than this value

created_on[lte]

Returns results where the created date is less then or equal to this value

created_by
string optional

Filter using the id of the user who created the passes

Example:
d4368a9a-3a83-4dc9-b3f2-ca755c8c61fa
pass_plan_id
string GUID optional

The id of the pass plan

Example:
4AD9C84FA60F9FE407140E20F707726A
contact_id
string GUID optional

The contact id to retrieve passes for

Example:
B76D7A65ACCE45B2E68DFDCAD1E31269
pass_code
string optional

Retrieve the specific pass code information (either pass_code or pass_code_hash) can be used

Example:
SLHY678993109PWE
pass_code_hash
string optional

Retrieve the hashed pass code (either pass_code or pass_code_hash) can be used

Example:
11f45e8377aad7bd38910f1a01b4ebda53605eb8
pin
string optional

If a pass_code has been specified then the relevant pass pin should be provided too (if applicable)

Example:
5663
life_cycle_state
array of Pass Life Cycle State (enum) optional

The life cycle state of the passes to be retrieved

Collection format: csv
printed
boolean optional

Whether the pass is printed (true) or not (false)

Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The pass ID

Example:
4AD9C84FA60F9FE407140E20F707726A
code
string

The pass code

Example:
1231231231231231
value
number

The pass value (if applicable)

Example:
100
pass_plan
Object

Details about the pass plan

id
string GUID

The pass plan identifier

Example:
b2bbd932-4b1c-f3e0-54f7-dc15ef715d98
name
string

The pass plan name

Example:
Xmas Gift Card
recipient
Object

The pass recipient information (if applicable)

id
string

Contact id

Example:
60F9FE407140E20F707726A4AD9C84FA
name
string

The recipient’s name

Example:
John Jonhson
code
string

The recipient’s contact code, if known

Example:
SI2952188
medium_type
string

The medium used to deliver the pass

Enumeration:
SMS
EMAIL
Example:
EMAIL
medium_value
string

The medium value for delivering the pass (can be email or phone number)

Example:
john@mail.com
currency
string

The currency of the pass

Example:
EUR
promotion
Object

Details of the promotion that the pass will consume (if a Promotion pass)

id
string

Promotion unique id

name
string

Promotion name

reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
printed
boolean

Defines whether the pass is printed (true), or electronic (false)

Example:
true
life_cycle_state
Unknown

The pass life cycle state

validity
Object

The validity of the pass - determines when the pass can be redeemed by

type
string

Validity type

Enumeration:
PERIOD

Pass is valid for a period of time

DATE

Pass is valid for a specific date

ALWAYS

Pass is always valid (never expires)

from_date
integer epoch

The ‘valid until’ date in case of ‘date’ type, or the ‘valid from’ date in case of ‘period’ type

Example:
1591703675
to_date
integer epoch

The ‘valid to’ date in case of ‘date’ type

Example:
1591703900
usage
Object

Pass usage details

allowed_usage
integer

How many times a Promotion type pass can be used

Example:
2
used_times
integer

The actual number of times that the pass has been used

Example:
1
redemption_entity
Object

Details available if the pass has been redeemed

entity_type
string

The type of entity that the pass was redeemed against

Enumeration:
WALLET
SUBSCRIPTION
ORDER
entity_id
string GUID

The id of the entity that the pass was redeemed against

Example:
4AD9C84FA60F9FE407140E20F707726A
entity_code
string

The code of the wallet or subscription, or the order number

Example:
O8904467
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/passes HTTP/1.1 
Get Pass
GET /passes/{id}

Retrieves the details for a single pass per API call.

Path variables

id
string required

The unique identifier of the pass to be retrieved

Example:
485ff648-38f0-4a0e-a99b-28cd293dfc7c

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The pass ID

Example:
4AD9C84FA60F9FE407140E20F707726A
code
string

The pass code

Example:
1231231231231231
value
number

The pass value

Example:
100
pass_plan
Object

Details about the pass plan

id
string GUID

The pass plan identifier

Example:
b2bbd932-4b1c-f3e0-54f7-dc15ef715d98
name
string

The pass plan name

Example:
Xmas Gift Card
recipient
Object

Recipient details

id
string

Contact id

Example:
60F9FE407140E20F707726A4AD9C84FA
name
string

Recipient’s name (if applicable)

Example:
John Smith
code
string

The recipient’s contact code (if available)

Example:
00001908
medium_type
string

The method used to deliver the pass

Enumeration:
SMS
EMAIL
Example:
EMAIL
medium_value
string

The value the delivery method used to deliver the pass (e.g. phone number or email)

Example:
john_smith@crm.com
currency
string

The currency of the pass

Example:
EUR
promotion
Object

Promotion details (if applicable)

id
string

The ID of the promotion that the pass will consume

Example:
79d7e281-d118-4069-9eb3-e79fdec2fd97
name
string

Promotion name

Example:
Welcome Back Promotion
reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
printed
boolean

Indicates a printed pass (true), or electronic pass (false)

Example:
true
life_cycle_state
string

The pass life cycle state

Enumeration:
DRAFT
ACTIVE
CANCELLED
REDEEMED
created_on
integer epoch

Created date

Example:
1591796310
created_by
string GUID

Created by id

Example:
4AD9C84FA60F9FE407140E20F707726A
updated_on
integer epoch

Date of update

updated_by
string GUID

Updated by id

Example:
4AD9C84FA60F9FE407140E20F707726A
validity
Object

Validity of the pass - when the pass can be redeemed by

type
string

Validity type

Enumeration:
PERIOD

Pass is valid for a period of time

DATE

Pass is valid for a specific date

ALWAYS

Pass is always valid (never expires)

period
integer

Period duration

Example:
1
period_uot
string

Period unit of time

Enumeration:
DAYS
MONTHS
YEARS
to_date
integer epoch

The ‘valid until’ date of redemption

Example:
1591903780
redemption_entity
string

Id of the entity against which the pass has been redeemed (e.g. a wallet id)

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
usage
Object

Used for PROMOTION type passes

allowed_usage
integer

How many times the PROMOTION type pass can be used

Example:
2
used_times
integer

The actual number of times that the pass has been used

Example:
1
pin
string

The pass pin

Example:
0558
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/passes/485ff648-38f0-4a0e-a99b-28cd293dfc7c HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A",
    "code": "1231231231231231",
    "value": 100,
    "pass_plan": {
        "id": "b2bbd932-4b1c-f3e0-54f7-dc15ef715d98",
        "name": "Xmas Gift Card"
    },
    "recipient": {
        "id": "60F9FE407140E20F707726A4AD9C84FA",
        "name": "John Smith",
        "code": "00001908",
        "medium_type": "EMAIL",
        "medium_value": "john_smith@crm.com"
    },
    "currency": "EUR",
    "promotion": {
        "id": "79d7e281-d118-4069-9eb3-e79fdec2fd97",
        "name": "Welcome Back Promotion"
    },
    "reward_offer": {
        "id": "c888dd7a-7476-538c-730a-9f924bd82d04",
        "name": "Birthday Offer"
    },
    "printed": true,
    "life_cycle_state": "ACTIVE",
    "created_on": 1591796310,
    "created_by": "4AD9C84FA60F9FE407140E20F707726A",
    "updated_on": 1,
    "updated_by": "4AD9C84FA60F9FE407140E20F707726A",
    "validity": {
        "type": "ALWAYS",
        "period": 1,
        "period_uot": "DAYS",
        "to_date": 1591903780
    },
    "redemption_entity": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "usage": {
        "allowed_usage": 2,
        "used_times": 1
    },
    "pin": "0558",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Redeem Pass
POST /passes

Redeem a single pass, the Contact’s wallet will be credited with the pass value.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
code
string required

The pass code (either pass code or code_hash must be specified)

Example:
SLHY678993109PWE
code_hash
string required

The hashed pass code (either code or code_hash must be specified)

Example:
11f45e8377aad7bd38910f1a01b4ebda53605eb8
otp
string nullable

The OTP (if applicable) - not in use

Example:
2345
pin
string nullable

The pass pin. Required if the pass has a pin

Example:
0587
value
number

The value of the pass to be redeemed (can only be set if the pass value = null)

Example:
100
contact_id
string GUID nullable

Id of the Contact redeeming the pass. If no contact_id is provided then a new Contact will be created using the pass code as the contact name (i.e. unnamed contact)

Example:
CEEE83D6E0804A30966F684B0269AD91
wallet_id
string GUID nullable

Id of Contact’s wallet to be credited with the pass value

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string GUID

The ID of the pass that has been successfully redeemed

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/passes HTTP/1.1 

Content-Type: application/json

{
    "code": "SLHY678993109PWE",
    "code_hash": "11f45e8377aad7bd38910f1a01b4ebda53605eb8",
    "otp": "2345",
    "pin": "0587",
    "value": 100,
    "contact_id": "CEEE83D6E0804A30966F684B0269AD91",
    "wallet_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Perform Passes Actions
PUT /passes/{id}/actions

Update the life cycle state or the expiration date for all passes of a single pass plan

Path variables

id
string GUID required

The unique identifier of the pass plan whose passes will be updated

Example:
103ddee2-cc09-e790-0f77-773ebb3b6c8c

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The type of action to be applied

Enumeration:
ACTIVATE

Activate all passes

CANCEL

Cancel all passes

EXPIRY_DATE

Change the expiration date of all passes

expiration_date
integer epoch nullable

The new expiration date (if changing expiration date)

Example:
1592919625

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/passes/103ddee2-cc09-e790-0f77-773ebb3b6c8c/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "EXPIRY_DATE",
    "expiration_date": 1592919625
}
Product Catalogue
Products
POST /products
PUT /products/{id}
DELETE /products/{id}
GET /products
GET /products/{id}
PUT /products/{id}/actions
POST /synchronise_products
GET /products/{id}/dependencies
GET /products/{id}/tiering
POST /products/{id}/media_groups
Create Product
POST /products

Create a new product. A single product can be created per Web API call

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
sku
string required

The product’s SKU which also has to be unique

Example:
ABC-123
name
string required

The product’s name. Its uniqueness depends on business rules

Example:
HD Decoder
description
string

A description of the product

Example:
High definition decoder
type_id
string required

The product’s type

family_id
string

The product’s family

brand_id
string

The product’s brand

categories
Array GUID

The supported categories for the product

Unique items: YES
string
Example:
12bb7786-e57a-2982-2ef9-185ee55b480b
validity_setting
string

Shows when the product is available for sale. If not specified, then it defaults to Always valid

Enumeration:
ALWAYS_VALID
SPECIFIC_PERIOD
Default:
ALWAYS_VALID
Example:
ALWAYS_VALID
validity_period
Object

The specific period of time during which the product is available for sale. Applicable ad required if the validity setting is set to “Specific Period”

from_date
integer
Example:
1627457572
to_date
integer
Example:
1627457572
upsells
Array of string

List of product identifiers which are considered as an Upsell for the new product

Unique items: YES
crosssells
Array of string

List of product identifiers which are considered as a Cross sell for the new product

Unique items: YES
variant_attributes
Array

List of variant attributes to be set on the new product. The allowed variant attributes are defined in the product’s type

Object
key
string required

The attribute’s key

Example:
size
value
string required

the attribute’s value

Example:
Small
composition
Object
item_type
string
Enumeration:
PRODUCT
TYPE
FAMILY
CATEGORY
COMPONENT_SET
Default:
PRODUCT
item_id
string
classification
string
Enumeration:
ADDON
MODIFIER
Default:
ADDON
Example:
ADDON
mandatory
boolean
Example:
true
priority
integer
Example:
1
minimum_quantity
integer
Example:
1
maximum_quantity
integer
Example:
3
price_inclusive
boolean
Example:
true
default_modifier_id
string

The identifier of the product that is set as default modifier

Example:
56786309-7a21-8097-e107-6e9aec401840
pricing
Object

Define a price for the new product.

rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
price
number required nullable

The product’s price. Mandatory but only for Flat prices. For the rest rate models, tiered prices must be specified

Example:
9.99
currency
string

The curency of the price

Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
billing_period
Object

Applicable and mandatory for termed and one-time services

duration
integer required
Example:
1
uot
string required
Example:
MONTHS
tiers
Array required nullable

Applicable and mandatory for Tiered, Volume and Stairstep models. At least two tiers must be specified.

Object
lower_tier
integer

The starting tier

Example:
1
upper_tier
integer

The upper tier. not required for the last range of tiers.

Example:
5
price
number

The price for eack tier range

Example:
8.99
accessibility
Object

Defines which organisations can be access and use it

inherit_family
boolean required

Defines whether accessibility is inherited by product family or not

Example:
false
type
string required nullable

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array nullable

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Unique items: YES
Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
measurement_unit_id
string

Applicable and mandatory only when creating Usage Services

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The product identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products HTTP/1.1 

Content-Type: application/json

{
    "sku": "ABC-123",
    "name": "HD Decoder",
    "description": "High definition decoder",
    "type_id": "",
    "family_id": "",
    "brand_id": "",
    "categories": [
        "12bb7786-e57a-2982-2ef9-185ee55b480b"
    ],
    "validity_setting": "ALWAYS_VALID",
    "validity_period": {
        "from_date": 1627457572,
        "to_date": 1627457572
    },
    "upsells": [
        ""
    ],
    "crosssells": [
        ""
    ],
    "variant_attributes": [
        {
            "key": "size",
            "value": "Small"
        }
    ],
    "composition": {
        "item_type": "PRODUCT",
        "item_id": "",
        "classification": "ADDON",
        "mandatory": true,
        "priority": 1,
        "minimum_quantity": 1,
        "maximum_quantity": 3,
        "price_inclusive": true,
        "default_modifier_id": "56786309-7a21-8097-e107-6e9aec401840"
    },
    "pricing": {
        "rate_model": "FLAT",
        "price": 9.99,
        "currency": "EUR",
        "tax_model": "TAX_INCLUSIVE",
        "billing_period": {
            "duration": 1,
            "uot": "MONTHS"
        },
        "tiers": [
            {
                "lower_tier": 1,
                "upper_tier": 5,
                "price": 8.99
            }
        ]
    },
    "accessibility": {
        "inherit_family": "false",
        "type": "SPECIFIC_ORG",
        "organisations": [
            "CAD1E31269B76D7A65ACCE45B2E68DFD"
        ]
    },
    "measurement_unit_id": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update Product
PUT /products/{id}

Updates an existing product

Path variables

id
string GUID required

The product identifier that will be updated

Example:
22386309-7a21-8097-e107-6e9aec401840

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
description
string
type_id
string

The product’s updated product type. When changing the type fo an existing product, restrictions are applied. The type can only change into another type of the same classification. In case of traceable physical goods, they cannot change into a type that marks them as nono-traceable

family_id
string
brand_id
string
validity_setting
string
Example:
ALWAYS_VALID
validity_period
Object
from_date
integer
to_date
integer
categories
Array GUID

The supported categories for the product

string
Example:
3302f723-01af-ecb7-b913-c3e649e35397
upsells
Array of string
crosssells
Array of string
variant_attributes
Array
Object
key
string
Example:
sze
value
string
composition
Array
Object
classfication
string
Enumeration:
ADDON
MODIFIER
Default:
ADDON
Example:
ADDON
item_type
string
Enumeration:
PRODUCT
TYPE
FAMILY
CATEGORY
COMPONENT_SET
Default:
PRODUCT
item_id
string
mandatory
boolean
Example:
true
minimum_quantity
integer
Example:
1
maximum_quantity
integer
Example:
3
price_inclusive
boolean
priority
integer

The priority of the composition

Example:
1
default_modifier_id
string

The identifier of the product that is set as default modifier

Example:
56786309-7a21-8097-e107-6e9aec401840
accessibility
Object

Defines which organisations can be access and use it

inherit_family
boolean required

Defines whether accessibility is inherited by product family or not

Example:
false
type
string required nullable

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array nullable

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Unique items: YES
Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
measurement_unit_id
string

Applicable only when updating Usage Services

Responses

200 OK
Body
Object
id
string GUID
Example:
22386309-7a21-8097-e107-6e9aec401840
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840 HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "type_id": "",
    "family_id": "",
    "brand_id": "",
    "validity_setting": "ALWAYS_VALID",
    "validity_period": {
        "from_date": 1,
        "to_date": 1
    },
    "categories": [
        "3302f723-01af-ecb7-b913-c3e649e35397"
    ],
    "upsells": [
        ""
    ],
    "crosssells": [
        ""
    ],
    "variant_attributes": [
        {
            "key": "sze",
            "value": ""
        }
    ],
    "composition": [
        {
            "classfication": "ADDON",
            "item_type": "PRODUCT",
            "item_id": "",
            "mandatory": true,
            "minimum_quantity": 1,
            "maximum_quantity": 3,
            "price_inclusive": true,
            "priority": 1,
            "default_modifier_id": "56786309-7a21-8097-e107-6e9aec401840"
        }
    ],
    "accessibility": {
        "inherit_family": "false",
        "type": "ACROSS_NETWORK",
        "organisations": [
            "CAD1E31269B76D7A65ACCE45B2E68DFD"
        ]
    },
    "measurement_unit_id": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "22386309-7a21-8097-e107-6e9aec401840"
}
Delete Product
DELETE /products/{id}

Deletes an existing product

Path variables

id
string GUID required

The product identifier that will be deleted

Example:
22386309-7a21-8097-e107-6e9aec401840

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/products/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 
List Products
GET /products

Returns a list of products that can be sold to customers, along with their basic information and price. Variant produts are excluded by default.

Request parameters

type_id
string optional
category_id
string optional
brand_id
string optional
family_id
string optional
fulfilled_by
string optional

The unique identifier of the organisation that will sell the product

contact_id
string optional

Use contact ID to check for any targetted promotions

show_promotions
boolean optional

Include list of promotions

is_variant
boolean optional
Default:
false
search_value
string optional

Search for a product using its SKU, its name or description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
composition
array of string optional
Collection format: csv
classification
array of string optional
Collection format: csv
include_creatives
boolean optional

Include Creatives in Response

availability
string optional

If not speficied, then all products are returned regardless of their availability

Enumeration:
ENABLED
DISABLED
ALL
Default:
ALL
is_provisionable
boolean optional

Filters products based on whether are provisionable or not

Example:
true
subscription_id
string optional

If specified, then return products that can be added on the specified subscription. Only termed services will be returned that have a price of the same billing period as the subscription’s.

Example:
4ec0809f-ed91-4b68-b912-5bd6064d901e
tag_ids
array of string optional

The tag id’s of the products for filtering

Collection format: csv
is_modifier
boolean optional

If specified, then only products marked as modifiers are returned. A produc tis marked as modifier through its type. If not specified, then it’s ignored and filtering is not applied.

Default:
false
Example:
false
validity_date
string optional

The date on which a product is sold/added as a charge or a service should also be within its validity date. Applicable only when listing products to get the services available to be ordered, added as charges or included in a subscription either as a new addition or through a service change. Filter based on the validity date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. validity_date[gte]=1618395497&validity_date[lt]=1618395497).

Enumeration:
validity_date[gt]

Returns results where the validity date is greater than this value

validity_date[gte]

Returns results where the validity date is greater than or equal to this value

validity_date[lt]

Returns results where the validity date is less than this value

validity_date[lte]

Returns results where the validity date is less than or equal to this value

include_stock
boolean optional

Defines whether stock balance information will be returned or not

Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
Example:
7CD9C84FA60F9FE407140E20F707726A
sku
string
Example:
ABC12345
name
string
Example:
Base TV
description
string
Example:
Basic TV & myFlix
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
type_composition
string
Enumeration:
FLAT
FIXED_BUNDLE
FLEXIBLE_BUNDLE
COMPOSITE
Example:
FLAT
number_of_running_promotions
integer
Example:
3
number_of_components
integer
Example:
2
number_of_variant_attributes
integer
Example:
2
number_of_variants
integer
Example:
9
number_of_prices
integer
Example:
3
availability
string
Example:
IN_STOCK
valid_since
integer
Example:
123434343
is_variant
boolean
is_stockable
boolean

Defines whether the product is a stockable product

Example:
true
can_be_rented
boolean

The product has at least one price of type Rental

type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
brand
Object
id
string
name
string
family
Object
id
string
name
string
categories
Array

The product categories

Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
pricing
Object
id
string

The price’s unique identifier

label
string

Price label that provides a small descritpion to when the prie is applied

Example:
VIP contacts
price
number

The product’s price. For Tiered/Volume/Stairstep rate models, this is the price of the first tier

Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
price_terms
Object
contract_period
Object
duration
integer
uot
string
billing_period
Object
duration
integer
uot
string
trial_period
Object
duration
integer
uot
string
terms_billing_cycles
integer

Service termed period covers X billing cycles

auto_renewed
boolean
Example:
true
price_model
string
Enumeration:
FIXED
VARIABLE
billing_model
string
Enumeration:
PRE_BILL
POST_BILL
tiers
Object

Returns only the first tier only for Tiered/Volume/Stairstep prices.

lower_tier
integer
upper_tier
integer
measurement_unit
Object
id
string
name
string
display_name
string
owner
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
in_stock
boolean

Applicable only for stockable physical goods

Example:
true
is_provisionable
boolean

Defines whether the product is provisionable or not

Example:
false
stock_information
Object

The product stock information (returned only if include_stock is set to true)

stock_balance
integer

The number of items that are in the warehouse (including reserved ones)

Example:
12
reserved
integer

The number of items that are reserved

Example:
11
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/products HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "7CD9C84FA60F9FE407140E20F707726A",
            "sku": "ABC12345",
            "name": "Base TV",
            "description": "Basic TV & myFlix",
            "classification": "TRACEABLE_PHYSICAL_GOOD",
            "type_composition": "FLAT",
            "number_of_running_promotions": 3,
            "number_of_components": 2,
            "number_of_variant_attributes": 2,
            "number_of_variants": 9,
            "number_of_prices": 3,
            "availability": "IN_STOCK",
            "valid_since": 123434343,
            "is_variant": true,
            "is_stockable": "true",
            "can_be_rented": true,
            "type": {
                "id": "c01ecd1b-ff1e-35c2-7236-59ae20339c78",
                "name": "Internal Transaction"
            },
            "brand": {
                "id": "",
                "name": ""
            },
            "family": {
                "id": "",
                "name": ""
            },
            "categories": [
                {
                    "id": "c8d83493-3f50-40df-adb0-762ec5f41863",
                    "name": "Delivery Purchase"
                }
            ],
            "pricing": {
                "id": "",
                "label": "VIP contacts",
                "price": 9.99,
                "currency": "EUR",
                "tax_model": "TAX_EXCLUSIVE",
                "rate_model": "FLAT",
                "price_terms": {
                    "contract_period": {
                        "duration": 1,
                        "uot": ""
                    },
                    "billing_period": {
                        "duration": 1,
                        "uot": ""
                    },
                    "trial_period": {
                        "duration": 1,
                        "uot": ""
                    },
                    "terms_billing_cycles": 1,
                    "auto_renewed": true,
                    "price_model": "FIXED",
                    "billing_model": "POST_BILL"
                },
                "tiers": {
                    "lower_tier": 1,
                    "upper_tier": 1
                },
                "measurement_unit": {
                    "id": "",
                    "name": "",
                    "display_name": ""
                }
            },
            "owner": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "PARTNER_LOGO",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ],
            "in_stock": "true",
            "is_provisionable": "false"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Product
GET /products/{id}

Retrieve detailed information for a specific product. Infromation fo a single product can be retrieved per Web API call.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
Example:
7CD9C84FA60F9FE407140E20F707726A
sku
string
Example:
ABC12345
name
string
Example:
Base TV
description
string
Example:
Basic TV & myFlix
classification
string
Enumeration:
TERMED_SERVICE
USAGE_SERVICE
EXPENSE
ONE_TIME_SERVICE
TRACEABLE_PHYSICAL_GOOD
NON_TRACEABLE_PHYSICAL_GOOD
Example:
TRACEABLE_PHYSICAL_GOOD
type_composition
string
Enumeration:
FLAT
FIXED_BUNDLE
FLEXIBLE_BUNDLE
COMPOSITE
Example:
FLAT
is_variant
boolean
Example:
true
is_stockable
boolean

Defines whether the product is a stockable product

Example:
true
validity_setting
string
Example:
SPECIFIC_PERIOD
number_of_running_promotions
integer
Example:
2
number_of_variants
integer
Example:
3
number_of_variant_attributes
integer
Example:
2
included_in_bundle
boolean

Indicates whether the product can also be sold as a bundle

in_stock
boolean

Shows whether the produc tis in stock or not. Applicable only for stockable physical goods.

Example:
true
type
Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
family
Object
id
string
name
string
brand
Object
id
string
name
string
categories
Array

The product categories

Object

Details about the event classification

id
string GUID

The category identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The category name

Example:
Delivery Purchase
measurement_unit
Object

The measurement unit of the product. Applicable for usage services only

id
string

The unique identifier of the measurement unit

Example:
895e8910-ebc2-d6c5-fb49-84bf99176171
name
string

The name of the measurement unit

Example:
Call minutes
display_name
string

The display name of the measurement unit

Example:
min.
validity_periods
Array
Object
from_date
integer
Example:
1234234234
to_date
integer
Example:
23423423424
variant_attributes
Array
Object
id
string
key
string
Example:
SIZE
value
string
mandatory
boolean
Example:
true
label
string
priority
integer

The priority of the variant attribute

Example:
1
composition
Array
Object
id
string
classification
string
Enumeration:
ADDON
MODIFIER
Default:
ADDON
Example:
ADDON
item_type
string
Enumeration:
PRODUCT
TYPE
FAMILY
CATEGORY
COMPONENT_SET
Default:
PRODUCT
item_id
string
name
string
sku
string
mandatory
boolean
Example:
true
minimum_quantity
integer
Example:
1
maximum_quantity
integer
Example:
5
price_inclusive
boolean
Example:
true
priority
integer

The priority of the composition

Example:
1
default_modifer
Object

The default modifier of this composition

id
string

The identifier of the product set as default modifier

Example:
23458910-ebc2-d6c5-fb49-84bf99176171
name
string

The name of the product set as default modifier

Example:
Premium Blend
upsells
Array
Object
id
string
sku
string
name
string
crosssells
Array
Object
id
string
sku
string
name
string
variants
Array
Object
id
string
sku
string
name
string
description
string
type
Object
id
string
name
string
variant_attributes
Array
Object
key
string
Example:
size
value
string
Example:
red
priority
integer

The priority of the variant

Example:
1
composite_product
Object

Applicable only for variant products

id
string
sku
string
name
string
accessbility
Object

Defines how the segment can be accessed from business network

inherit_family
boolean

Defines whether accessibility is inherited by product family or not

Example:
true
type
string

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
CRM
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7CD9C84FA60F9FE407140E20F707726A",
    "sku": "ABC12345", 
    "name": "Base TV",
    "description": "Basic TV & myFlix",
    "classification": "TERMED_SERVICE",
    "type_composition": "FLEXIBLE_BUNDLE",
    "is_variant": true,
    "is_stockable": true,
    "validity_setting": "SPECIFIC_PERIOD",
    "number_of_running_promotions": 2,
    "number_of_variants": 3,
    "number_of_variant_attributes": 2,
    "included_in_bundle": true,
    "in_stock": "true",
    "type": {
        "id": "",
        "name": ""
    },
    "family": {
        "id": "",
        "name": ""
    },
    "brand": {
        "id": "",
        "name": ""
    },
    "categories": [
        {
            "id": "895e8910-ebc2-d6c5-fb49-84bf99176171",
            "name": "Coffee Milks"
        }
    ],
    "measurement_unit": {
        "id": "895e8910-ebc2-d6c5-fb49-84bf99176171",
        "name": "Call minutes",
        "display_name": "min."
    },
    "validity_periods": [
        {
            "from_date": 1234234234,
            "to_date": 23423423424
        }
    ],
    "variant_attributes": [
        {
            "id": "",
            "key": "SIZE",
            "value": "",
            "mandatory": true,
            "label": "",
            "priority": 1
        }
    ],
    "composition": [
        {
            "id": "",
            "classification": "ADDON",
            "item_type": "FAMILY",
            "item_id": "",
            "name": "",
            "sku": "",
            "mandatory": true,
            "minimum_quantity": 1,
            "maximum_quantity": 5,
            "price_inclusive": true,
            "priority": 1
        }
    ],
    "upsells": [
        {
            "id": "",
            "sku": "",
            "name": ""
        }
    ],
    "crosssells": [
        {
            "id": "",
            "sku": "",
            "name": ""
        }
    ],
    "variants": [
        {
            "id": "",
            "sku": "",
            "name": "",
            "description": "",
            "type": {
                "id": "",
                "name": ""
            },
            "variant_attributes": [
                {
                    "key": "size",
                    "value": "red"
                }
            ],
            "priority": 1
        }
    ],
    "composite_product": {
        "id": "",
        "sku": "",
        "name": ""
    },
    "accessbility": {
        "inherit_family": "true",
        "type": "SPECIFIC_ORG",
        "organisations": [
            {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "CRM"
            }
        ]
    },
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "LANDING_PAGE_BACKGROUND_IMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Perform Product Actions
PUT /products/{id}/actions

Path variables

id
string required

The product’s unique identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string
Enumeration:
ENABLE
DISABLE
organisations
Array

The organisation identifiers for which the product action is applied.

Object
organisation_id
string GUID

The organisation identifiers for which the product action is applied.

supply_method
Array

Applicable only on Enabling/Disabling a product.

string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 2
PUT https://sandbox.crm.com/backoffice/v1/products/{id}/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "DISABLE",
    "organisations": [
        {
            "organisation_id": "",
            "supply_method": [
                "DELIVERY"
            ]
        }
    ]
}
Synchronise Products
POST /synchronise_products

Performs product synchornization between the products that exist in the POS client over to CRM.COM.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
products
Array

Details about the products to synchornise

Object
sku
string required

The product sku

Example:
SKU0001
name
string nullable

The product name

Example:
Iced Latte
description
string nullable

The product description

Example:
Product Description
type
Object nullable

The product type (if type is provided, id or name should be specified)

id
string GUID required nullable

The product type identifier

Example:
d94ef0f0-59a1-aa28-b49d-0d1edcc864fe
name
string required nullable

The product type name

Example:
Cold
brand
Object nullable

Details about the product brand (if brand is provided, id or name should be specified)

id
string GUID required nullable

The product brand identifier

Example:
13b265cb-a607-5d22-1ce5-52ae3585fcdc
name
string required nullable

The product brand name

Example:
Fresh Brew Inc
family
Object nullable

Details about the product family (if family is provided, id or name should be specified)

id
string GUID required nullable

The product family identifier

Example:
21f9ed6d-ff93-afce-c7f0-b1e96e6b8a04
name
string required nullable

The product family name

Example:
Homebrew
categories
Array nullable

Details about the product categories (for each provided category, id or name or code should be specified)

Object
id
string GUID required nullable

The product category identifier

Example:
070631e8-c34b-9dd7-24e7-074cc5b3a7e8
name
string required nullable

The product category name

Example:
Drinks
code
string required nullable

The product category code

Example:
500
validity_period
Object nullable

Defines the period that the product will be valid (if not specified, will be always valid)

from_date
integer epoch nullable

The date from which the product will be valid

Example:
11598357038
to_date
integer epoch nullable

The date up to which the product will be valid

Example:
1598357038
tax_rate
Object nullable

Details about the product tax rate (id or name should be specified)

id
string GUID required nullable

The tax rate identifier

Example:
d1b59cfd-f3dd-1ae0-e96f-935d51ae66b0
name
string required nullable

The tax rate name

Example:
5% Tax
pricing
Object nullable

Details about the product pricing

rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
price
number

The price (amount). Mandatory only for Flat rate models

Example:
9.99
currency
string

The price currency (3 code)

Example:
EUR
tiers
Array nullable

Details about the pricing tiering (required for Tiered/Volume/Stairstep based rate models). Mandatory and required for these 3 rate models. At leas two tiers must be provided

Object
lower_tier
integer required

The lowest tier

Example:
1
upper_tier
integer

The top tier. Not required for the last tier range

Example:
5
price
number required

The tier price (amount)

Example:
8.99
variant_attributes
Array nullable

Details about the product variant attributes

Object
key
string required

The variant attribute’s key

Example:
size
value
string required

The variant attribute value

Example:
Medium
components
Array nullable

Details about the product components (applicable if the synced product is variant attribute or bundle)

Object
sku
string required nullable

The component product sku that will be used as component (sku or family, category or product type should be specified)

Example:
CPSKU01
product_family
Object

The component product family that will be used as component (sku, family, category or product type should be specified)

id
string GUID required nullable

The product family identifier (id or name should be specified)

Example:
ab93d2e9-f6b4-ca48-15e1-bff3a468ab4a
name
string required nullable

The product family name (id or name should be specified)

Example:
Dry
product_type
Object

The component product type that will be used as component (sku or family, category or product type should be specified)

id
string GUID required nullable

The product type identifier (id or name should be specified)

Example:
ab93d2e9-f6b4-ca48-15e1-bff3a468ab4a
name
string required nullable

The product type identifier (id or name should be specified)

Example:
Extras
product_category
Object

The component product category that will be used as component (sku or family, category or product type should be specified)

id
string GUID required nullable

The product category identifier (id, name or code should be specified)

Example:
ab93d2e9-f6b4-ca48-15e1-bff3a468ab4a
name
string required nullable

The product category name (id, name or code should be specified)

Example:
Milks
code
string required nullable

The product category code (id, name or code should be specified)

Example:
500
inclusive
boolean nullable

Defines if pricing is inclusive

Default:
false
Example:
true
min_amount
integer nullable

The maximum number of components that should be added (applicable only for product family and type)

Default:
0
max_amount
integer nullable

The maximum number of components that should be added (applicable only for product family and type)

Default:
0
mandatory
boolean nullable

Defines whether the component must be added to the product or not

Default:
false
Example:
true
classification
string nullable

Defines the classification of the component

Enumeration:
ADDON

eg. A cookie that can be added with a coffee selection

MODIFIER

eg. Sugar that will be added in a coffee

default_modifier_id
string nullable

The identifier of the product that is set as default modifier

Example:
56786309-7a21-8097-e107-6e9aec401840
measurement_unit
Object nullable

The product’s measurement unit. A uique name should be specified

id
string GUID nullable

The measurement unit identifier

Example:
014a8d1a-62f4-2b0d-84af-16c298a76fe9
name
string nullable

The measurement unit name

Example:
Liters
main_product_sku
string required nullable

The unique product sku of variant_attribute (required if the synced product is a variant attribute of another product)

Example:
SKU000A
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
owner
Object nullable

Defines the organisation that owns such product (if not specified, defaults to business)

organisation
Object required nullable

Identify the owner based on organisation

id
string GUID required

The organisation identifier

Example:
d0905f88-85fa-2d2b-f06f-c59855ec996d
tap
Object required nullable

Identify the owner based on organisation’s tap

id
string GUID required nullable

The tap identifier

Example:
e8fd06db-3b1d-3685-4bc4-eaa20eb71977
code
string required nullable

The tap code

Example:
0000257024

Responses

200 200

OK

Body
Object
id
string GUID

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).

Example:
a781bbc1-9067-c384-52fe-43586f89110a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2

Synchronize stand-alone POS products

POST https://sandbox.crm.com/backoffice/v1/synchronise_products HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "products": [
        {
            "sku": "SUGAR001",
            "name": "Brown Sugar",
            "description": "Brown Sugar",
            "type": {
                "name": "Condiments"
            },
            "family": {
                "name": "Coffee & Tea Condiments"
            },
            "categories": [{
                "code": "100"
            }]
        },
        {
            "sku": "FFM001",
            "name": "Full Fat",
            "description": "Full Fat Milk",
            "type": {
                "name": "Condiments"
            },
            "family": {
                "name": "Coffee & Tea Condiments"
            },
            "categories": [{
                "code": "100"
            },{
                "code": "1"
            }]
        },
        {
            "sku": "MFREESP01",
            "name": "Freddo Espresso Medio",
            "description": "Freddo Espresso Medio",
            "type": {
                "name": "Wet"
            },
            "family": {
                "name": "FREDDO"
            },
            "categories": [{
                "code": "210"
            }]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a781bbc1-9067-c384-52fe-43586f89110a"
}

Synchronize POS products with pricing and category based components

POST https://sandbox.crm.com/backoffice/v1/synchronise_products HTTP/1.1 

api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json

{
    "products": [
        {
            "sku": "SUGAR001",
            "name": "Brown Sugar",
            "description": "Brown Sugar",
            "type": {
                "name": "Condiments"
            },
            "family": {
                "name": "Coffee & Tea Condiments"
            },
            "categories": [{
                "code": "100"
            }],
            "pricing": {
                "rate_model": "FLAT",
                "tax_model": "TAX_INCLUSIVE",
                "price": 1.99,
                "currency": "EUR"
            }
        },
        {
            "sku": "FFM001",
            "name": "Full Fat",
            "description": "Full Fat Milk",
            "type": {
                "name": "Condiments"
            },
            "family": {
                "name": "Coffee & Tea Condiments"
            },
            "categories": [{
                "code": "100"
            },{
                "code": "1"
            }],
            "pricing": {
                "rate_model": "FLAT",
                "tax_model": "TAX_INCLUSIVE",
                "price": 1.99,
                "currency": "EUR"
            }
        },
        {
            "sku": "MFREESP01",
            "name": "Freddo Espresso Medio",
            "description": "Freddo Espresso Medio",
            "type": {
                "name": "Wet"
            },
            "family": {
                "name": "FREDDO"
            },
            "categories": [{
                "code": "210"
            }],
            "pricing": {
                "rate_model": "FLAT",
                "tax_model": "TAX_INCLUSIVE",
                "price": 5.99,
                "currency": "EUR"
            },
            "components": [
                {
                    "product_category":  {
                        "code": "500"
                    },
                    "mandatory": false,
                    "classification": "MODIFIER",
                    "min_amount": 0,
                    "max_amount": 1,
                    "inclusive": true
                },
                {
                    "product_category":  {
                        "code": "100"
                    },
                    "mandatory": true,
                    "classification": "MODIFIER",
                    "min_amount": 1,
                    "max_amount": 2
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a781bbc1-9067-c384-52fe-43586f89110a"
}
Get Product Dependencies
GET /products/{id}/dependencies

Returns a list of products on which the specified product has a dependency to

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
item_type
string
Example:
TYPE
item_id
string
Example:
MOVIES
name
string
classification
string
Example:
TERMED_SERVICE
dependency_type
string
Example:
CANNOT_COEXIST
operator
string
Example:
ANY
dependencies
Array
Object
item_type
string
Example:
PRODUCT
item_id
string
name
string
products
Array
Object
id
string
sku
string
name
string
pricing
Object
price
number
Example:
9.99
currency
string
Example:
EUR
rate_model
string
Example:
FLAT
tax_model
string
Example:
TAX_EXCLUSIVE
price_terms
Array
Object
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
auto_renew
boolean
Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id}/dependencies HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "item_type": "TYPE",
            "item_id": "MOVIES",
            "name": "",
            "classification": "TERMED_SERVICE",
            "dependency_type": "CANNOT_COEXIST",
            "operator": "ANY",
            "dependencies": [
                {
                    "item_type": "PRODUCT",
                    "item_id": "",
                    "name": "",
                    "products": [
                        {
                            "id": "",
                            "sku": "",
                            "name": "",
                            "pricing": {
                                "price": 9.99,
                                "currency": "EUR",
                                "rate_model": "FLAT",
                                "tax_model": "TAX_EXCLUSIVE",
                                "price_terms": [
                                    {
                                        "billing_period": {
                                            "duration": 1,
                                            "uot": "MONTHS"
                                        },
                                        "auto_renew": true
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}
Get Tier Path Products
GET /products/{id}/tiering

Returns a list of produts included within the specified product’s tier path

Path variables

id
string required

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
change_type
string optional
Enumeration:
UPGRADE
DOWNGRADE
billing_period_duration
integer optional
billing_period_uot
string optional
currency
string optional
contact_id
string optional

The contact who wants to make a change. Required when contact pricing exists for the service to change to.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
Example:
3FD9C84FA60F9FE407140E20F707726A
sku
string
Example:
abc-123456
name
string
Example:
3Play
tier_level
integer
Example:
3
type_compositin
string
change_type
string
Enumeration:
UPGRADDE
DOWNGRADE
prices
Array
Object
id
string

The unique identifier of the price terms

price
number
label
string

Small description of the price

Example:
VIP Contacts
currency
string
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
price_terms
Object
billing_period
Object
duration
integer
uot
string
terms_billing_cycles
integer
Example:
1
auto_renewed
boolean
Example:
true
contract_period
Object
duration
integer
Example:
1
uot
string
trial_period
Object
duration
integer
Example:
1
uot
string
price_model
string
Enumeration:
FIXED
VARIABLE
billing_model
string
Enumeration:
PRE_BILL
POST_BILL
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id}/tiering HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3FD9C84FA60F9FE407140E20F707726A",
            "sku": "abc-123456",
            "name": "3Play",
            "tier_level": 3,
            "type_compositin": "",
            "change_type": "UPGRADDE",
            "prices": [
                {
                    "id": "",
                    "price": 1,
                    "label": "VIP Contacts",
                    "currency": "",
                    "tax_model": "TAX_INCLUSIVE",
                    "price_terms": {
                        "billing_period": {
                            "duration": 1,
                            "uot": ""
                        },
                        "terms_billing_cycles": 1,
                        "auto_renewed": true,
                        "contract_period": {
                            "duration": 1,
                            "uot": ""
                        },
                        "trial_period": {
                            "duration": 1,
                            "uot": ""
                        },
                        "price_model": "VARIABLE",
                        "billing_model": "POST_BILL"
                    }
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Product Media Groups
POST /products/{id}/media_groups

Link a product with one or many Media Groups

Path variables

id
string GUID required

The product identifier that will be updated

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Notes

MEDIA UPLOAD

Uploading media for a product requires the execution of the following APIs

  1. Create new Media Group
  2. Create Product Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK
Allowance

Web APIs to set the usage allowance per product price

POST /prices/{id}/allowance
POST /prices/{id}/allowance/products
POST /prices/{id}/allowance/conditions
PUT /prices/{id}/allowance
PUT /prices/{id}/allowance/products
PUT /prices/{id}/allowance/conditions
GET /prices/{id}/allowance
GET /prices/{id}/allowance/products
GET /prices/{id}/allowance/conditions
Add Allowance
POST /prices/{id}/allowance

Adds allowance for one of the product’s prices

Path variables

id
string required

Request body

Object
accumulated_allowance
Object
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99

Responses

201 Created
Body
Object
id
string

The product price’s unique identifier

Example:
8c54d563-b991-4b76-8a83-557c08166f95
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance HTTP/1.1 

Content-Type: application/json

{
    "accumulated_allowance": {
        "cash_limits": {
            "per_transaction": 9.99,
            "per_day": 19.99,
            "per_billing_cycle": 59.99
        }
    }
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "8c54d563-b991-4b76-8a83-557c08166f95"
}
Add Products Allowance
POST /prices/{id}/allowance/products

Adds products allowance for one of the product’s prices

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
products_allowance
Array required

List of products and/or product types that can be consumed, along with their limits (if any)

Object
item_type
string required
Enumeration:
PRODUCT
TYPE
Example:
PRODUCT
item_id
string required

Unique idnetifier of the product or product type

Example:
8c54d563-b991-4b76-8a83-557c08166f95
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99
usage_amounts
Object
per_transaction
number

Maximum allowed usage amount per transaction

Example:
9.99
per_day
number

Maximum allowed usage amount per day

Example:
19.99
per_billing_cycle
number

Maximum allowed usage amount per billing cycle

Example:
59.99

Responses

201 Created
Body
Object
id
string

The product price’s unique identifier

Example:
8c54d563-b991-4b76-8a83-557c08166f95
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance HTTP/1.1 

Content-Type: application/json

{
    "products_allowance": [
        {
            "item_type": "PRODUCT",
            "item_id": "8c54d563-b991-4b76-8a83-557c08166f95",
            "cash_limits": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            },
            "usage_amounts": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            }
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "8c54d563-b991-4b76-8a83-557c08166f95"
}
Add Allowance Conditions
POST /prices/{id}/allowance/conditions

Add conditions to product allowance. Multiple conditions can be added per product price.

Path variables

id
string required

Request body

Object
organisations
Array nullable

A list of organisations at which the orders/purchases that consume alloawance are performed. The list includes a set of distinct organisation identifiers

Unique items: YES
Object
id
string

Organisation unique identifier

Responses

201 Created
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance/conditions HTTP/1.1 

Content-Type: application/json

{
    "organisations": [
        {
            "id": ""
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": ""
}
Update Allowance
PUT /prices/{id}/allowance

Adds allowance for one of the product’s prices

Path variables

id
string required

Request body

Object
accumulated_allowance
Object
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99

Responses

200 OK
Body
Object
id
string

The product price’s unique identifier

Example:
8c54d563-b991-4b76-8a83-557c08166f95
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance HTTP/1.1 

Content-Type: application/json

{
    "accumulated_allowance": {
        "cash_limits": {
            "per_transaction": 9.99,
            "per_day": 19.99,
            "per_billing_cycle": 59.99
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "8c54d563-b991-4b76-8a83-557c08166f95"
}
Update Products Allowance
PUT /prices/{id}/allowance/products

Updates products allowance for one of the product’s prices

Path variables

id
string required

The unique identifier of the product price

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
products_allowance
Array required

List of products and/or product types that can be consumed, along with their limits (if any)

Object
item_type
string required
Enumeration:
PRODUCT
TYPE
Example:
PRODUCT
item_id
string required

Unique idnetifier of the product or product type

Example:
8c54d563-b991-4b76-8a83-557c08166f95
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99
usage_amounts
Object
per_transaction
number

Maximum allowed usage amount per transaction

Example:
9.99
per_day
number

Maximum allowed usage amount per day

Example:
19.99
per_billing_cycle
number

Maximum allowed usage amount per billing cycle

Example:
59.99

Responses

200 OK
Body
Object
id
string

The product price’s unique identifier

Example:
8c54d563-b991-4b76-8a83-557c08166f95
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance/products HTTP/1.1 

Content-Type: application/json

{
    "products_allowance": [
        {
            "item_type": "PRODUCT",
            "item_id": "8c54d563-b991-4b76-8a83-557c08166f95",
            "cash_limits": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            },
            "usage_amounts": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            }
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "8c54d563-b991-4b76-8a83-557c08166f95"
}
Update Allowance Conditions
PUT /prices/{id}/allowance/conditions

Update conditions to product allowance. Multiple conditions can be updated but for a single product price.

Path variables

id
string required

Request body

Object
organisations
Array nullable

A list of organisations at which the orders/purchases that consume alloawance are performed. The list includes a set of distinct organisation identifiers

Unique items: YES
Object
id
string

Organisation unique identifier

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance/conditions HTTP/1.1 

Content-Type: application/json

{
    "organisations": [
        {
            "id": ""
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Get Allowance
GET /prices/{id}/allowance

Returns usage allowance of a specific product price.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
accumulated_allowance
Object
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "accumulated_allowance": {
        "cash_limits": {
            "per_transaction": 9.99,
            "per_day": 19.99,
            "per_billing_cycle": 59.99
        }
    }
}
Get Product Allowance
GET /prices/{id}/allowance/products

Returns a list of products allowance for one of the product’s prices

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
products_allowance
Array required

List of products and/or product types that can be consumed, along with their limits (if any)

Object
item_type
string required
Enumeration:
PRODUCT
TYPE
Example:
PRODUCT
item_id
string required

Unique idnetifier of the product or product type

Example:
8c54d563-b991-4b76-8a83-557c08166f95
name
string

Name of product or product type

Example:
Family plan
number
string

Product SKU

Example:
F000001
cash_limits
Object
per_transaction
number

Maximum allowed amount of money that usage consumption costs per transaction

Example:
9.99
per_day
number

Maximum allowed amount of money that usage consumption costs per day

Example:
19.99
per_billing_cycle
number

Maximum allowed amount of money that usage consumption costs per billing cycle

Example:
59.99
usage_amounts
Object
per_transaction
number

Maximum allowed usage amount per transaction

Example:
9.99
per_day
number

Maximum allowed usage amount per day

Example:
19.99
per_billing_cycle
number

Maximum allowed usage amount per billing cycle

Example:
59.99

Responses

201 Created
Body
Object
id
string

The product price’s unique identifier

Example:
8c54d563-b991-4b76-8a83-557c08166f95
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance HTTP/1.1 

Content-Type: application/json

{
    "products_allowance": [
        {
            "item_type": "PRODUCT",
            "item_id": "8c54d563-b991-4b76-8a83-557c08166f95",
            "cash_limits": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            },
            "usage_amounts": {
                "per_transaction": 9.99,
                "per_day": 19.99,
                "per_billing_cycle": 59.99
            }
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "8c54d563-b991-4b76-8a83-557c08166f95"
}
Get Allowance Conditions
GET /prices/{id}/allowance/conditions

Returns a set of conditions to product allowance.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
organisations
Array
Object
id
string
name
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/prices/{id}/allowance/conditions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "organisations": [
        {
            "id": "",
            "name": ""
        }
    ]
}
Product Variants
POST /products/{id}/variants
PUT /products/{id}/variants/{variant_id}
DELETE /products/{id}/variants/{variant_id}
GET /products/{id}/variants
Create Product Variants
POST /products/{id}/variants

Creates the Variant products of a composite product.

Path variables

id
string GUID required

The composite product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
variants
Array

The variants of the product (product id and sku/name are semi-optional)

Object
product_id
string GUID required nullable

The existing product identifier that will be added as variant

Example:
704a96be-4bcf-f5cc-12a2-c5038e37d8c5
sku
string required nullable

The new product sku that will be added as variant

name
string required nullable

The new product name that will be added as variant

description
string nullable

The new product description that will be added as variant

variant_attributes
Array required

The variant attributes

Min items: 1
Object
key
string required

The variant key

Example:
size
value
string required

The variant value

Example:
Small
priority
integer

The priority of the variant

Example:
1

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The product variant identifier

Example:
22386309-7a21-8097-e107-6e9aec401840
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840/variants HTTP/1.1 

Content-Type: application/json

{
    "variants": [
        {
            "sku": "",
            "name": "",
            "description": "",
            "variant_attributes": [
                {
                    "key": "size",
                    "value": "Small"
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "22386309-7a21-8097-e107-6e9aec401840"
}
Update Product Variant Priority
PUT /products/{id}/variants/{variant_id}

Update an existing variant priority

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840
variant_id
string GUID required

The variant product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec4018QQ

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
priority
integer

The priority of the component

Example:
1

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/products/{id}/components/{component_id} HTTP/1.1 

Content-Type: application/json

{
    "classification": "ADDON",
    "mandatory": true,
    "minimum_quantity": 1,
    "maximum_quantity": 5,
    "price_inclusive": true
}
Remove Product Variant
DELETE /products/{id}/variants/{variant_id}

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840
variant_id
string GUID required

The variant product’s unique identifer

Example:
22386309-7a21-8097-e107-6e9aec4018QQ

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840/variants/22386309-7a21-8097-e107-6e9aec4018QQ HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Get Product Variants
GET /products/{id}/variants

Returns the list of a composite product’s variants

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840

Request parameters

supply_method
string optional

How the order will be supplied

Enumeration:
DELIVERY
PICK_UP
ON_SITE
fulfilled_by
string optional

The unique identifier of the organisation providing the product

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string
sku
string
name
string
description
string
type
Object
id
string
name
string
variant_attributes
Array
Object
key
string
Example:
size
value
string
Example:
Small
label
string
pricing
Array
Object
price
number

The product’s price. If a Variant product does not have its own price, then the Composite products price is returned. For Tiered/VOlume/Stairstep rate models, this it the price of the first tier level.

Example:
9.99
currency
string
Example:
EUR
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
supply_method
string
Enumeration:
DELIVERY
PICK_UP
taxes
Array
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
tiers
Object

Returns only the first tier only for Tiered/Volume/Stairstep prices.

lower_tier
integer
upper_tier
integer
number_of_tiers
integer
creatives
Array
Object
id
string
Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string
Example:
PROFILEIMAGE
width
integer
Example:
2159
height
integer
Example:
3075
format
string
Example:
jpg
url
string
Example:
https://assets.crm.com/image/logo.jpg
public_id
string
Example:
crm-com/image
media
Array
Object
width
integer
Example:
200
height
integer
Example:
300
url
string
Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
availability
string
Example:
DISABLED
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840/variants HTTP/1.1 
Product Components
POST /products/{id}/components
PUT /products/{id}/components/{component_id}
DELETE /products/{id}/components/{component_id}
GET /products/{id}/components
Add Product Component
POST /products/{id}/components

Adds a new component in a flexible bundle product’s composition

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
item_type
string
Enumeration:
PRODUCT
TYPE
FAMILY
CATEGORY
COMPONENT_SET
Default:
PRODUCT
item_id
string required

The unique identifier of the prouct or prodct type or product family or product category, depending on item_type selection

classification
string
Enumeration:
ADDON
MODIFIER
Default:
ADDON
Example:
ADDON
mandatory
boolean

Applicable and required but only for product components.

Default:
false
Example:
true
minimum_quantity
integer

Applicable for product type/family/category components

Example:
1
maximum_quantity
integer

Applicable for product type/family/category components

Example:
5
price_inclusive
boolean

Defines whether the component’s price is included in the bundles price or not

Default:
false
Example:
true
priority
integer

The priority of the component

Example:
1
default_modifier_id
string

The identifier of the product that is set as default modifier

Example:
56786309-7a21-8097-e107-6e9aec401840

Responses

200 OK
Body
Object
id
string

The new product component’s unique identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840/components HTTP/1.1 

Content-Type: application/json

{
    "item_type": "PRODUCT",
    "item_id": "",
    "classification": "ADDON",
    "mandatory": true,
    "minimum_quantity": 1,
    "maximum_quantity": 5,
    "price_inclusive": true,
    "priority": 1,
    "default_modifier_id": "56786309-7a21-8097-e107-6e9aec401840"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Product Component
PUT /products/{id}/components/{component_id}

Update an existing component in a bundle product

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840
component_id
string GUID required
Example:
22386309-7a21-8097-e107-6e9aec4018QQ

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification
string
Example:
ADDON
mandatory
boolean
Example:
true
minimum_quantity
integer
Example:
1
maximum_quantity
integer
Example:
5
price_inclusive
boolean
Example:
true
priority
integer

The priority of the component

Example:
1
default_modifier_id
string

The identifier of the product that is set as default modifier

Example:
56786309-7a21-8097-e107-6e9aec401840

Responses

200 OK
Body
Object
id
string

The updated product component’s uniqe identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/products/22386309-7a21-8097-e107-6e9aec401840/components/22386309-7a21-8097-e107-6e9aec4018QQ HTTP/1.1 

Content-Type: application/json

{
    "classification": "ADDON",
    "mandatory": true,
    "minimum_quantity": 1,
    "maximum_quantity": 5,
    "price_inclusive": true,
    "priority": 1,
    "default_modifier_id": "56786309-7a21-8097-e107-6e9aec401840"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Remove Product Component
DELETE /products/{id}/components/{component_id}

Removes a component from a flexible product bundle

Path variables

id
string GUID required

The product’s unique idetifier

Example:
22386309-7a21-8097-e107-6e9aec401840
component_id
string GUID required

The product component unique identifier

Example:
22386309-7a21-8097-e107-6e9aec401840

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/products/{id}/components/{copmonent_id} HTTP/1.1 

HTTP/1.1 204 No Content 
Get Product Components
GET /products/{id}/components

Returns a list of products that could be added as components of a flexible bundle

Path variables

id
string required

Request parameters

billing_period
string optional

Used when a component is added in a flexible termed service bundle in order to retrieve service components that have a price with the same billing cycle as the selected bundle

billing_period_uot
string optional

Applicable and required when a billing period is also passed as an input

Enumeration:
DAYS
WEEKS
MONTHS
YEARS
service_id
string optional

Applicable only for termed services of flexible bundle composition. If specified, then it returns the service bundle’s existing (non-cancelled) service components and merges them with any additional components that can be included in the service bundle.

search_value
string optional

Search for a product available to be added as a bundle component using its SKU or name

include_creatives
boolean optional

Include Creatives in response

Default:
false

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
item_type
string
Enumeration:
PRODUCT
FAMILY
TYPE
CATEGORY
COMPONENT_SET
item_id
string
mandatory
boolean
Example:
true
name
string

The name of the component

Example:
Milk Options Cappuccino Massimo
display_name
string

The display name of the component

Example:
Milks
classification
string
Example:
MODIFIER
price_inclusive
boolean
Example:
true
minimum_quantity
integer
Example:
1
maximum_quantity
integer
Example:
3
default_modifier
Object

The default modifier of this component

id
string

The identifier of the product set as default modifier

Example:
23458910-ebc2-d6c5-fb49-84bf99176171
sku
string
name
string

The name of the product set as default modifier

Example:
Almond milk
products
Array
Object
id
string
sku
string
name
string
description
string
is_included
boolean

If set to True, then the produc tis alreay included in the bundle

Example:
true
pricing
Array
Object
id
string

The price terms identifier

price
number
Example:
9.99
currency
string
Example:
EUR
rate_model
string
Example:
FLAT
tax_model
string
Example:
TAX_INCLUSIVE
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
taxes
Array
Object
id
string
name
string
tax_code
string
Example:
VAT
percentage
integer
Example:
1
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id}/components HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "item_type": "COMPONENT_SET",
            "item_id": "",
            "mandatory": true,
            "name": "Milk Options Cappuccino Massimo",
            "display_name": "Milks",
            "classification": "MODIFIER",
            "price_inclusive": true,
            "minimum_quantity": 1,
            "maximum_quantity": 3,
            "default_modifier": {
                "id": "23458910-ebc2-d6c5-fb49-84bf99176171",
                "sku": "",
                "name": "Almond milk"
            },
            "products": [
                {
                    "id": "",
                    "sku": "",
                    "name": "",
                    "description": "",
                    "is_included": "true",
                    "pricing": [
                        {
                            "id": "",
                            "price": 9.99,
                            "currency": "EUR",
                            "rate_model": "FLAT",
                            "tax_model": "TAX_INCLUSIVE",
                            "supply_method": "DELIVERY",
                            "taxes": [
                                {
                                    "id": "",
                                    "name": "",
                                    "tax_code": "VAT",
                                    "percentage": 1
                                }
                            ]
                        }
                    ],
                    "creatives": [
                        {
                            "id": "CA123456789AQWSXZAQWS1236547896541",
                            "usage_type": "PROFILEIMAGE",
                            "width": 2159,
                            "height": 3075,
                            "format": "jpg",
                            "url": "https://assets.crm.com/image/logo.jpg",
                            "public_id": "crm-com/image",
                            "media": [
                                {
                                    "width": 200,
                                    "height": 300,
                                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
Product Tags
POST /products/{id}/tags
PUT /products/{id}/tags
DELETE /products/{id}/tags/{tag_id}
GET /products/{id}/tags
Add Product Tags
POST /products/{id}/tags

The following process adds tags to a product.

Path variables

id
string required

The product GUID

Example:
HRDGSWRSFVSDSDBSDSSDDE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
FDHNFDBR675765ghdh
Example 1
POST https://sandbox.crm.com/backoffice/v1/products/HRDGSWRSFVSDSDBSDSSDDE/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "FDHNFDBR675765ghdh"
        }
    ]
}
Update Product Tags
PUT /products/{id}/tags

The following process updates tags for a product.

Path variables

id
string required

The contact GUID

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
JKGSJGFKDGJKFGFSJK
Example 1
PUT https://sandbox.crm.com/backoffice/v1/products/{id}/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "JKGSJGFKDGJKFGFSJK"
        }
    ]
}
Delete Product Tag
DELETE /products/{id}/tags/{tag_id}

Deletes a tag on a product.

Path variables

id
string required

The id of the product.

Example:
JFGJKSFGJFSGH
tag_id
string required

The id of the tag

Example:
KJDFHKJGFSJHG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/products/JFGJKSFGJFSGH/tags/KJDFHKJGFSJHG HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
Get Product Tags
GET /products/{id}/tags

The following process retrieves the tags for a product

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

the tag ID

Example:
JKGJHFSDJHGDSJHGA
name
string

Name of Tag

Example:
Maintenance
colour
string

Colour of tag

Example:
The colour of the tag
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id}/tags HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JKGJHFSDJHGDSJHGA",
            "name": "Maintenance",
            "colour": "The colour of the tag"
        }
    ]
}
Provisioning
POST /products/{id}/providers
PUT /products/{id}/providers
DELETE /products/{id}/providers/{provider_id}
GET /products/{id}/providers
Add Product Provisioning Provider
POST /products/{id}/providers

Add a new provisioning provider on a specific product

Path variables

id
string GUID required

The product (identifier) that provider details will be added

Example:
16dec2ff-f6fb-4d44-c388-0f1f95c03890

Notes

Within CRM, only products of type traceable physical goods, termed and one time services can be provisioned. Creating such products (given that their type is provisioned enabled) requires to specify the related provider details as described bellow

  • Traceable Physical Goods: must specify by which integrator(s) can be provisioned
  • Termed & One-Time Services: must specify by which integrator(s) can be provisioned and the supported external reference per provider (a service can be provisioned by more than one provider)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
integration_id
string GUID required

The provider (integrator identifier) that will provision the product

Example:
8812f0cf-7256-2647-ffbd-a7356232f318
external_references
Array nullable

The provider (integrator) external reference (applicable and required only for termed and one-time services)

Unique items: YES
Example:
[
    "EX-REF-01"
]
string
Example:
EX-REF-01

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/16dec2ff-f6fb-4d44-c388-0f1f95c03890/providers HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "integration_id": "8812f0cf-7256-2647-ffbd-a7356232f318",
        "external_references": [
            "EX-REF-01"
        ]
    }
]

HTTP/1.1 200 OK 
Update Product Provisioning Provider
PUT /products/{id}/providers

Update an existing provisioning provider on a specific product

Path variables

id
string GUID required

The product (identifier) that provider details will be updated

Example:
16dec2ff-f6fb-4d44-c388-0f1f95c03890

Notes

Within CRM, only products of type traceable physical goods, termed and one time services can be provisioned. Creating such products (given that their type is provisioned enabled) requires to specify the related provider details as described bellow

  • Traceable Physical Goods: must specify by which integrator(s) can be provisioned
  • Termed & One-Time Services: must specify by which integrator(s) can be provisioned and the supported external reference per provider (a service can be provisioned by more than one provider)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
id
string GUID required

The product provider (identifier) that will be updated

Example:
10c44dba-6cbe-1015-1ba3-662ca3c24c36
integration_id
string GUID required

The provider (integrator identifier) that will provision the product

Example:
8812f0cf-7256-2647-ffbd-a7356232f318
external_references
Array required nullable

The provider (integrator) external reference (applicable and required only for termed and one-time services)

Example:
[
    "EX-REF-01"
]
string
Example:
EX-REF-01

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/products/16dec2ff-f6fb-4d44-c388-0f1f95c03890/providers HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "id": "10c44dba-6cbe-1015-1ba3-662ca3c24c36",
        "integration_id": "8812f0cf-7256-2647-ffbd-a7356232f318"
    }
]

HTTP/1.1 200 OK 
Delete Product Provisioning Provider
DELETE /products/{id}/providers/{provider_id}

Remove an existing provisioning provider from a specific product

Path variables

id
string GUID required

The product (identifier) that provider details will be deleted

Example:
16dec2ff-f6fb-4d44-c388-0f1f95c03890
provider_id
string GUID required

The provider (identifier) that provider details will be removed

Example:
16dec2ff-f6fb-4d44-c388-0f1f95c03890

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/products/16dec2ff-f6fb-4d44-c388-0f1f95c03890/providers16dec2ff-f6fb-4d44-c388-0f1f95c03890 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Product Provisioning Providers
GET /products/{id}/providers

Get a list of all provisioning providers of a specific product

Path variables

id
string GUID required

The product (identifier) that provider details will be retrieved

Example:
97ab56be-077b-984a-7499-760f9f15ecd4

Request parameters

integration_id
string optional

The identifier of the Provisioning provider integration

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The product provider identifier

Example:
c9d10f2c-7511-ebc7-1158-3bfbb59ca5c1
integration
Object

Details about the provider integrator that provisions the product

id
string GUID

The provider integratot identifier

Example:
246af5e7-dd6c-affe-18a5-e8988f12a3da
name
string

The provider integratot name

Example:
Irdeto
media_url
string
external_references
Array

The provider (integrator) external reference (applicable only for termed and one-time services)

Example:
[
    "EXT-REF-01"
]
string
Example:
EXT-REF-01
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/products/97ab56be-077b-984a-7499-760f9f15ecd4/providers HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "c9d10f2c-7511-ebc7-1158-3bfbb59ca5c1",
            "integration": {
                "id": "246af5e7-dd6c-affe-18a5-e8988f12a3da",
                "name": "Irdeto",
                "media_url": ""
            },
            "external_references": [
                "EXT-REF-01"
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Licenses
PUT /products/{id}/licenses
GET /products/{id}/licenses
DELETE /products/{id}/licenses/{license_id}
Add License to Product
PUT /products/{id}/licenses

Assign a license to a product. License can be set only to termed services owned by the service owner

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
id
string GUID

The identifier of the license to be assigned to the product

Example:
9a20b05c-4869-6361-6f78-fd90fdfdd9ed

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/product/{id}/license HTTP/1.1 

Content-Type: application/json

{
    "license": "9a20b05c-4869-6361-6f78-fd90fdfdd9ed"
}

HTTP/1.1 200 OK 
Get Product License
GET /products/{id}/licenses

Retrieves licensing information of a product. License can be set only to termed services owned by the service owner

Path variables

id
string GUID required

The product (identifier) for which the assigned license will be retrieved

Example:
84e80fe1-869c-86ef-cc61-3d75df58dba5

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
license
Object

List of assets/modules/features to which access is granted through the license

id
string GUID

The license identifier

Example:
197c88c4-bcb2-2faf-2c71-ce26128364a2
name
string

The name of the license

Example:
Trial License
description
string

The description of the license

Example:
This is free Trial License with limited access to features
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/product/84e80fe1-869c-86ef-cc61-3d75df58dba5/license/197c88c4-bcb2-2faf-2c71-ce26128364a2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "license": {
        "id": "197c88c4-bcb2-2faf-2c71-ce26128364a2",
        "name": "Trial License",
        "description": "This is free Trial License with limited access to features"
    }
}
Remove License from Product
DELETE /products/{id}/licenses/{license_id}

Removes assigned license from a product

Path variables

id
string GUID required

The product (identifier) for which the assigned license will be removed

Example:
84e80fe1-869c-86ef-cc61-3d75df58dba5
license_id
string GUID required

The license (identifier) which will be removed

Example:
674f28db-65f8-b608-ed77-43ea40af0b2d

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

Successfull Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/products/84e80fe1-869c-86ef-cc61-3d75df58dba5/license/674f28db-65f8-b608-ed77-43ea40af0b2d HTTP/1.1 

HTTP/1.1 200 OK 
Pricing

Manage prices of prodcuts across the Product Catalogue. A product (regardles of its type, composition or classification) might have multiple prices. A price can be set for either a specific product or for all products within a family of products.

POST /products/{id}/prices
PUT /products/{id}/prices
GET /products/{id}/prices
DELETE /products/{id}/prices/{price_id}
POST /product_families/{id}/prices
PUT /product_families/{id}/prices
DELETE /product_families/{id}/prices/{price_id}
GET /product_families/{id}/prices
Add Product Price
POST /products/{id}/prices

Adds new prices to a product.

Path variables

id
string required

The product’s unique idetifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
label
string

Small description of the price

Example:
VIP Contacts
price
number
Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
supply_method
string
Example:
DELIVERY
price_type
string
Enumeration:
SALE
RENTAL
Default:
SALE
Example:
SALE
sales_model
string
Enumeration:
RETAIL
WHOLESALE
Default:
RETAIL
Example:
RETAIL
country
string
Example:
GRC
bundle_product_id
string

Price applied when the product was sold as part of the specified bundle.

used_via_product_id
string

Applicable when setting up prices for usage services only. The price is applied only when the usage is consumed through the specified termed or one time service. Only termed or one time services can be specified

tiers
Array
Object
lower_tier
integer
Example:
1
upper_tier
integer
Example:
5
price
number
Example:
8.99
price_terms
Object
contract_period
Object
duration
integer
Example:
1
uot
string
billing_period
Object
duration
integer
Example:
1
uot
string
trial_period
Object
duration
string
uot
string
auto_renewed
boolean
Example:
true
terms_billing_cycles
integer
Example:
1
price_model
string
Example:
FIXED
billing_model
string
Example:
POST_BILL
rental_service_id
string
segments
Array
Object
id
string
contacts
Array
Object
id
string

Responses

201 Created
Body
Object
id
string

The identifier of the new product price

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/{id}/prices HTTP/1.1 

Content-Type: application/json

[
    {
        "label": "VIP Contacts",
        "price": 9.99,
        "currency": "EUR",
        "tax_model": "TAX_INCLUSIVE",
        "rate_model": "FLAT",
        "supply_method": "DELIVERY",
        "price_type": "SALE",
        "sales_model": "RETAIL",
        "country": "GRC",
        "bundle_product_id": "",
        "used_via_product_id": "",
        "tiers": [
            {
                "lower_tier": 1,
                "upper_tier": 5,
                "price": 8.99
            }
        ],
        "price_terms": {
            "contract_period": {
                "duration": 1,
                "uot": ""
            },
            "billing_period": {
                "duration": 1,
                "uot": ""
            },
            "trial_period": {
                "duration": "",
                "uot": ""
            },
            "auto_renewed": true,
            "terms_billing_cycles": 1,
            "price_model": "FIXED",
            "billing_model": "POST_BILL",
            "rental_service_id": ""
        },
        "segments": [
            {
                "id": ""
            }
        ],
        "contacts": [
            {
                "id": ""
            }
        ]
    }
]

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": ""
}
Update Product Price
PUT /products/{id}/prices

Path variables

id
string required

The product’s unique idetifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
price
number required nullable

The updated product price. Mandatory if rate model is set to Flat

Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
price_type
string required
Enumeration:
SALE
RENTAL
Default:
SALE
country
string
Example:
GRC
bundle_product_id
string
used_via_product_id
string

Applicable when setting up prices for usage services only. The price is applied only when the usage is consumed through a specicid termed or one time service

tiers
Array required nullable

Applicable and mandatory for rate models Tiered/VOlume/Stairstep. At least 2 tiers must be specified.

Object
lower_tier
integer required
Example:
1
upper_tier
integer

Required for all ranges apart from the last one.

Example:
5
price
number required
Example:
8.99
price_terms
Object
terms_billing_cycles
integer
Example:
12
billing_period
Object
duration
string
uot
string
trial_period
Object
duration
integer
uot
string
auto_renewed
boolean
Example:
true
contract_period
Object
duration
string
uot
string
price_model
string
Enumeration:
FIXED
VARIABLE
billing_model
string
Enumeration:
PRE_BILL
POST_BILL
rental_service_id
string

The product identifier of the rental service. Applicable only for physicl goods and only if the customer selects to rent them on ordering. Only expense services can be specified. A rental price will include the rental service and the billing period as its price terms

used_by_product_id
string

The product that gives access to consuming a usage service. This product must either be a termed service or a one-time service. Applicable only when setting up prices for usage services.

sales_model
string

The price for the the particular sales model

Enumeration:
RETAIL
WHOLESALE
segments
Array

This price is applicable for particular segment/s.

Object
id
string
contacts
Array

This price is applicable for particular contact/s.

Object
id
string
label
string

Small description of the price

Example:
VIP contacts

Responses

200 OK
Body
Object
id
string

The idetifier of the updated product

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/products/{id}/prices HTTP/1.1 

Content-Type: application/json

[
    {
        "price": 9.99,
        "currency": "EUR",
        "tax_model": "TAX_INCLUSIVE",
        "rate_model": "FLAT",
        "supply_method": "DELIVERY",
        "price_type": "SALE",
        "country": "GRC",
        "bundle_product_id": "",
        "used_via_product_id": "",
        "tiers": [
            {
                "lower_tier": 1,
                "upper_tier": 5,
                "price": 8.99
            }
        ],
        "price_terms": {
            "terms_billing_cycles": 12,
            "billing_period": {
                "duration": "",
                "uot": ""
            },
            "trial_period": {
                "duration": 1,
                "uot": ""
            },
            "auto_renewed": true,
            "contract_period": {
                "duration": "",
                "uot": ""
            },
            "price_model": "VARIABLE",
            "billing_model": "PRE_BILL",
            "rental_service_id": "",
            "used_by_product_id": ""
        },
        "sales_model": "RETAIL",
        "segments": [
            {
                "id": ""
            }
        ],
        "contacts": [
            {
                "id": ""
            }
        ],
        "label": "VIP contacts"
    }
]

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Product Prices
GET /products/{id}/prices

Get a list of all prices of a specific product

Path variables

id
string required

The product’s unique identifier

Request parameters

country
string optional
currency
string optional
rate_model
string optional
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
supply_method
string optional
Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
sales_model
string optional
Enumeration:
WHOLESALE
RETAIL
segment_id
array of string optional
Collection format: csv
contact_id
array of string optional
Collection format: csv
billing_period
string optional

Used when a termed service product will be added on a subscription. Therefore, use the subscription’s billing cycle as a condition to list prices that include the same billing cycle in their price terms.

billing_period_uot
string optional

Applicable and required only when a billing period parameter is specified

Enumeration:
DAYS
WEEKS
MONTHS
YEARS
label
string optional

Search for a price using its label

Example:
VIP contacts

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Array
Object
id
string
group_id
string
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
Default:
FLAT
price
number
Example:
9.99
currency
string
Example:
EUR
country
string
Example:
GRC
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
valid_since
integer
Example:
12345678
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
price_type
string
Enumeration:
SALE
RENTAL
measurement_unit
Object

The measurement unit per which the price will be applied. Applicable for prices of usage services only. The usage service’s measurement unit is returned.

id
string
name
string
display_name
string
used_via_product
Object

Applicable when setting up prices for usage services only. The price is applied only when the usage is consumed through a specicid termed or one time service

id
string
sku
string
name
string
bundle_product
Object
id
string
sku
string
name
string
price_terms
Object

Applicable only for temed service products

billing_period
Object
duration
string
uot
string
terms_billing_cycles
integer
auto_renewed
boolean
Example:
true
contract_period
Object
duration
integer
uot
string
trial_period
Object
duration
integer
uot
string
price_model
string
Enumeration:
FIXED
VARIABLE
billing_model
string
Enumeration:
PRE_BILL
POST_BILL
rental_service
Object

The product identifier of the rental service. Applicable only for physicl goods and only if the customer selects to rent them on ordering. Only expense services can be specified. A rental price will include the rental service and the billing period as its price terms

id
string
sku
string
name
string
tiers
Array
Object
price
number
Example:
9.99
lower_tier
integer
Example:
1
upper_tier
integer
Example:
5
sales_model
string
Enumeration:
RETAIL
WHOLESALE
segments
Array
Object
id
string
contacts
Array
Object
id
string
label
string

Small description of the price

Example:
VIP contacts
Example 1
GET https://sandbox.crm.com/backoffice/v1/products/{id}/prices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "",
        "group_id": "",
        "rate_model": "FLAT",
        "price": 9.99,
        "currency": "EUR",
        "country": "GRC",
        "tax_model": "TAX_INCLUSIVE",
        "valid_since": 12345678,
        "supply_method": "DELIVERY",
        "price_type": "SALE",
        "measurement_unit": {
            "id": "",
            "name": "",
            "display_name": ""
        },
        "used_via_product": {
            "id": "",
            "sku": "",
            "name": ""
        },
        "bundle_product": {
            "id": "",
            "sku": "",
            "name": ""
        },
        "price_terms": {
            "billing_period": {
                "duration": "",
                "uot": ""
            },
            "terms_billing_cycles": 1,
            "auto_renewed": true,
            "contract_period": {
                "duration": 1,
                "uot": ""
            },
            "trial_period": {
                "duration": 1,
                "uot": ""
            },
            "price_model": "VARIABLE",
            "billing_model": "PRE_BILL",
            "rental_service": {
                "id": "",
                "sku": "",
                "name": ""
            }
        },
        "tiers": [
            {
                "price": 9.99,
                "lower_tier": 1,
                "upper_tier": 5
            }
        ],
        "sales_model": "RETAIL",
        "segments": [
            {
                "id": ""
            }
        ],
        "contacts": [
            {
                "id": ""
            }
        ],
        "label": "VIP contacts"
    }
]
Delete Product Price
DELETE /products/{id}/prices/{price_id}

Delete an existing product price.

Path variables

id
string required
price_id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/products/{id}/prices/{price_id} HTTP/1.1 

HTTP/1.1 200 OK 
Add Product Family Prices
POST /product_families/{id}/prices

Adds new prices to a product family.

Path variables

id
string required

The product family’s unique idetifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
price
number required

The price of products for this product family. Mandatoy but only for Flat prices

Example:
9.99
currency
string required

the price’s currency. Defaults to the system’s currency if not specified

Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
supply_method
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
country
string
Example:
GRC
tiers
Array required nullable

Applicable nad mandatory for Tiered/Volume/Stairstep rate models. At least two tiers must be specified.

Object
lower_tier
integer required
Example:
1
upper_tier
integer
Example:
5
price
number required
Example:
8.99
price_terms
Object
contract_period
Object
duration
integer
Example:
1
uot
string
billing_period
Object
duration
integer
Example:
1
uot
string
trial_period
Object
duration
string
uot
string
auto_renewed
boolean
Example:
true
terms_billing_cycles
integer
Example:
1
price_model
string
Example:
FIXED
billing_model
string
Example:
PRE_BILL
sales_model
string
Enumeration:
WHOLESALE
RETAIL
contacts
Array
Object
id
string
segments
Array
Object
id
string

Responses

201 Created
Body
Object
id
string

The identifier of the new product price

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/product_families/{id}/prices HTTP/1.1 

Content-Type: application/json

[
    {
        "price": 9.99,
        "currency": "EUR",
        "tax_model": "TAX_INCLUSIVE",
        "rate_model": "STAIRSTEP",
        "supply_method": "PICK_UP",
        "country": "GRC",
        "tiers": [
            {
                "lower_tier": 1,
                "upper_tier": 5,
                "price": 8.99
            }
        ],
        "price_terms": {
            "contract_period": {
                "duration": 1,
                "uot": ""
            },
            "billing_period": {
                "duration": 1,
                "uot": ""
            },
            "trial_period": {
                "duration": "",
                "uot": ""
            },
            "auto_renewed": true,
            "terms_billing_cycles": 1,
            "price_model": "FIXED",
            "billing_model": "PRE_BILL"
        },
        "sales_model": "RETAIL",
        "contacts": [
            {
                "id": ""
            }
        ],
        "segments": [
            {
                "id": ""
            }
        ]
    }
]

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": ""
}
Update Product Family Prices
PUT /product_families/{id}/prices

Path variables

id
string required

The product family’s unique idetifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
id
string
price
number
Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSVE
TAX_EXCLUSIVE
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
supply_method
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
country
string
Example:
GRC
tiers
Array
Object
lower_tier
integer
Example:
1
upper_tier
integer
Example:
5
price
number
Example:
8.99
price_terms
Object
contract_period
Object
duration
integer
Example:
1
uot
string
billing_period
Object
duration
integer
Example:
1
uot
string
trial_period
Object
duration
integer
Example:
1
uot
string
terms_billing_cycles
integer
Example:
1
auto_renewed
boolean
Example:
true
price_model
string
Example:
FIXED
billing_model
string
Example:
PRE_BILL
sales_model
string
Enumeration:
WHOLESALE
RETAIL
contacts
Array
Object
id
string
segments
Array
Object
id
string

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/product_families/{id}/prices HTTP/1.1 

Content-Type: application/json

[
    {
        "id": "",
        "price": 9.99,
        "currency": "EUR",
        "tax_model": "TAX_INCLUSVE",
        "rate_model": "STAIRSTEP",
        "supply_method": "PICK_UP",
        "country": "GRC",
        "tiers": [
            {
                "lower_tier": 1,
                "upper_tier": 5,
                "price": 8.99
            }
        ],
        "price_terms": {
            "contract_period": {
                "duration": 1,
                "uot": ""
            },
            "billing_period": {
                "duration": 1,
                "uot": ""
            },
            "trial_period": {
                "duration": 1,
                "uot": ""
            },
            "terms_billing_cycles": 1,
            "auto_renewed": true,
            "price_model": "FIXED",
            "billing_model": "PRE_BILL"
        },
        "sales_model": "WHOLESALE",
        "contacts": [
            {
                "id": ""
            }
        ],
        "segments": [
            {
                "id": ""
            }
        ]
    }
]

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Product Family Price
DELETE /product_families/{id}/prices/{price_id}

Path variables

id
string required
price_id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

200 OK

The request has succeeded

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/product_families/{id}/prices/{price_id} HTTP/1.1 

HTTP/1.1 200 OK 
List Product Family Prices
GET /product_families/{id}/prices

Get a list of all prices of a specific product family

Path variables

id
string required

The product family’s unique identifier

Request parameters

country
string optional
currency
string optional
rate_model
string optional
contact_id
array of string optional
Collection format: csv
segment_id
array of string optional
Collection format: csv
sales_model
string optional
Enumeration:
RETAIL
WHOLESALE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Array
Object
id
string
group_id
string
price
number
Example:
9.99
currency
string
Example:
EUR
rate_model
string
Enumeration:
FLAT
TIERED
VOLUME
STAIRSTEP
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
country
string
Example:
GRC
valid_since
integer
Example:
12345678
supply_method
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
price_terms
Object
contract_period
Object
duration
integer
Example:
1
uot
string
billing_period
Object
duration
integer
Example:
1
uot
string
trial_period
Object
duration
integer
Example:
1
uot
string
terms_billing_cycles
integer
Example:
1
auto_renewed
boolean
Example:
true
price_model
string
Example:
FIXED
billing_model
string
Example:
PRE_BILL
tiers
Array

Available for prices with Tiered/Volume/Stairstep rate models

Object
price
number
Example:
9.99
lower_tier
integer
Example:
1
upper_tier
integer
Example:
5
sales_model
string
Enumeration:
WHOLESALE
RETAIL
contacts
Array
Object
id
string
segments
Array
Object
id
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/product_families/{id}/prices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "",
        "group_id": "",
        "price": 9.99,
        "currency": "EUR",
        "rate_model": "VOLUME",
        "tax_model": "TAX_INCLUSIVE",
        "country": "GRC",
        "valid_since": 12345678,
        "supply_method": "DIRECT_SALE",
        "price_terms": {
            "contract_period": {
                "duration": 1,
                "uot": ""
            },
            "billing_period": {
                "duration": 1,
                "uot": ""
            },
            "trial_period": {
                "duration": 1,
                "uot": ""
            },
            "terms_billing_cycles": 1,
            "auto_renewed": true,
            "price_model": "FIXED",
            "billing_model": "PRE_BILL"
        },
        "tiers": [
            {
                "price": 9.99,
                "lower_tier": 1,
                "upper_tier": 5
            }
        ],
        "sales_model": "WHOLESALE",
        "contacts": [
            {
                "id": ""
            }
        ],
        "segments": [
            {
                "id": ""
            }
        ]
    }
]
Promotions
POST /promotions
PUT /promotions/{id}
DELETE /promotions/{id}
GET /promotions
GET /promotions/{id}
PUT /promotions/{id}/actions
POST /promotions/{id}/media_groups
Create Promotion
POST /promotions

Creates a new Promotion.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
Example:
Sales season
short_description
string
Example:
£10 off
long_description
string
availability
Object
from_date
integer

EPOCH of start Date

Example:
1234566
to_date
integer

EPOCH of end date

Example:
1234566

Responses

201 Created
Body
Object
id
string

The unique identifier of the new offer

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/promotions HTTP/1.1 

Content-Type: application/json

{
    "name": "Sales season",
    "type": "AUTO_APPLIED",
    "short_description": "£10 off",
    "long_description": "",
    "discount_option": "AMOUNT",
    "discount_value": 1,
    "validity_setting": "ALWAYS",
    "availability": {
        "from_date": 1234566,
        "to_date": 1234566
    }
}
Update Promotion
PUT /promotions/{id}

Updates the abasic information of a promotion. A single promotion can be pdated per Web API call.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
Example:
Sales season
short_description
string
Example:
£10 off
long_description
string
availability
Array
Object
from_date
integer
Example:
1234566
to_date
integer
Example:
1234566

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated promotion

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/promotions/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "Sales season",
    "short_description": "£10 off",
    "long_description": "",
    "discount_option": "PERCENTAGE",
    "discount_value": 1,
    "validity_setting": "SPECIFIC_PERIOD",
    "availability": [
        {
            "from_date": 1234566,
            "to_date": 1234566
        }
    ]
}
Delete Promotion
DELETE /promotions/{id}

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/promotions/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List Promotions
GET /promotions

Returns a list of promotions that can be applied per organisation, for specific period etc

Request parameters

organisations
array of string optional
Collection format: csv
Unique items: YES
offering_items
array of string optional

Products that get a discount from the promotions

Collection format: csv
Unique items: YES
id_type
string optional

Required if a list of award items is specified. Indicates if the item is a product or a product type, brand, family or category.

Enumeration:
SKU
TYPE
FAMILY
BRAND
search_value
string optional

Search for an promotion using its name

life_cycle_state
string optional

Use life cycle

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
segments
string optional

List of customer segments

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
Example:
7CD9C84FA60F9FE407140E20F707726A
name
string
Example:
Sales season
short_description
string
long_description
string
life_cycle_state
string
Example:
INACTIVE
availability
Object
from_date
integer
Example:
1
to_date
integer
Example:
1
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/promotions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        
        {
            "id": "7CD9C84FA60F9FE407140E20F707726A",
            "type": "AUTO_APPLIED",
            "name": "Sales season",
            "short_description": "",
            "long_description": "",
            "life_cycle_state": "INACTIVE",
            "discount_setting":"PERCENTAGE",
            "discount_value":5,
            "availability": {
                "from_date": 1,
                "to_date": 1
            },
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "type": "MARKETING",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/offer.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
                        }
                    ]
                }
            ]
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Promotion
GET /promotions/{id}

Retrieves detailed information for a Promotion

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
Example:
7CD9C84FA60F9FE407140E20F707726A
name
string
Example:
Sales season
life_cycle_state
string
short_description
string
Example:
£10 off
long_description
string
availability
Object
from_date
integer
Example:
1234566
to_date
integer
Example:
1234566
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
Example 1
GET https://sandbox.crm.com/backoffice/v1/promotions/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7CD9C84FA60F9FE407140E20F707726A",
    "name": "Sales season",
    "life_cycle_state": "",
    "short_description": "£10 off",
    "long_description": "",
    "availability": {
        "from_date": 1234566,
        "to_date": 1234566
    },
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "PROFILEIMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Perform Promotion Actions
PUT /promotions/{id}/actions

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string
Enumeration:
ACTIVE
INACTIVE

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/promotions/{id}/actions HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "ACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Promotion Media Groups
POST /promotions/{id}/media_groups

Link a promotion with one or many Media Groups

Path variables

id
string GUID required

The promotion identifier that will be updated

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Notes

MEDIA UPLOAD

Uploading media for a promotion requires the execution of the following APIs

  1. Create new Media Group
  2. Create Promotion Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK 
Targets
GET /promotions/{id}/targets
POST /promotions/{id}/targets/contacts
POST /promotions/{id}/targets/organisations
POST /promotions/{id}/targets/timings
POST /promotions/{id}/targets/baskets
Get Promotion Targets
GET /promotions/{id}/targets

Retrieves the promotion target conditions for, customer_segments, venues, products

Path variables

id
string GUID required

The Prootion’s identifier whose target conditions will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
segments
Array

Details about contact segment conditions

Object
id
string GUID

The segment identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The segment name

Example:
VIP Customers
description
string

The segment description

Example:
All customers that are classified as VIP
size
integer

The number of results for that segment

Example:
112
organisations
Array

Details about location conditions based on organisation

Object
id
string GUID

The organisation identifier

Example:
234234234234-23423sdfs-324234sfsf
type
string

The organisation type

Enumeration:
MERCHANT
VENUE
name
string

The organisation name

Example:
Bravo Bakery
locations
Array

The organisation locations

Object
name
string

The name of the location

Example:
Head Office
address_line_1
string
Example:
Elia Papakyriakou 21
address_line_2
string
Example:
7 Tower Stars
state_province_county
string
Example:
Egkomi
town_city
string
Example:
Nicosia
postal_code
string
Example:
2415
country_code
string
Example:
CY
care_of
string
lat
string
Example:
35.157115
lon
string
Example:
33.313719
googleplaceid
string
Example:
ChIJrTLr-GyuEmsRBfy61i59si0
timings
Object
fixed_period
Object
start_date
number
end_date
number
availability
Array
Object
day
integer
Example:
6
month
integer
Example:
11
start_time
string
Example:
13:00
end_time
string
Example:
14:00
basket
Object
rules
Array
Object
payment_method_type
string
Enumeration:
CASH
CARD
supply_method
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
value
number

The basket’s value.

currency
string
quantity
string

The number of items included in the basket

products
Object
groups
Array
Object
group
string

name of Group

Example:
G1
operator
string

group outer operator

Example:
AND
conditions
Array

List of conditions

Object
condition
string
operator
string
Example:
AND
product
Object
id
string
id_type
string
Enumeration:
ID
SKU
FAMILY
BRAND
sku
string
name
string

Product name

quantity
integer
value
number
currency
string
billing_cycle
Object
duration
integer
uot
string
contract_period
Object
duration
integer
uot
string
services
Array

List of services to which a contact must already be subscribed to in order to get the promotion. Only termed services can be specified. Available and applicable only when the basket item is a termed service or a product type of Termed service classification.

Object
id
string

Product identifier

Example:
1af94364-b0f2-d656-aed6-bd3e3978cab4
sku
string

Product SKU

Example:
TV0001
name
string

Product Name

Example:
Films
quantity
number

Subscirption service shoulf have this minimum quantity

Example:
2
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/promotions/6A24D2B5E44F44B28451FE021FCAD51E/targets HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "segments": [
        { 
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "VIP Customers",
            "description": "All customers that are classified as VIP",
            "size": 112
        }
    ],
    "organisations": [
        {
            "id": "234234234234-23423sdfs-324234sfsf",
            "type": "VENUE",
            "name": "Bravo Bakery",
            "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",
                    "care_of": "",
                    "lat": "35.157115",
                    "lon": "33.313719",
                    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ]
        }
    ],
    "timings": {
        "fixed_period": {
            "start_date": 1,
            "end_date": 1
        },
        "availability": [
            {
                "day": 6,
                "month": 11,
                "start_time": "13:00",
                "end_time": "14:00"
            }
        ]
    },
    "basket": {
        "rules": [
            {
                "payment_method_type": "CARD",
                "supply_method": "DIRECT_SALE",
                "value": 1,
                "currency": "",
                "quantity": ""
            }
        ],
        "products": {
            "groups": [
                {
                    "group": "G1",
                    "operator": "AND",
                    "conditions": [
                        {
                            "condition": "",
                            "operator": "AND",
                            "product": {
                                "id": "",
                                "id_type": "FAMILY",
                                "sku": "",
                                "name": ""
                            },
                            "quantity": 1,
                            "value": 1,
                            "currency": "",
                            "billing_cycle": {
                                "duration": 1,
                                "uot": ""
                            },
                            "contract_period": {
                                "duration": 1,
                                "uot": ""
                            },
                            "services": [
                                {
                                    "id": "1af94364-b0f2-d656-aed6-bd3e3978cab4",
                                    "sku": "TV0001",
                                    "name": "Films",
                                    "quantity": 2
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}
Add Contacts Targets
POST /promotions/{id}/targets/contacts

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
segments
Array required

List of contact segments aaded as promotion targets

Min items: 1
Unique items: YES
string guid

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/{id}/targets/contacts HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "segments": [
        ""
    ]
}

HTTP/1.1 201 Created 
Add Location Target
POST /promotions/{id}/targets/organisations

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
organisations
Array of string required

List of organisations

Min items: 1
Unique items: YES

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/{id}/targets/organisations HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "organisations": [
        ""
    ]
}
Add Timings
POST /promotions/{id}/targets/timings

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
fixed_period
Object nullable
start_date
integer
Example:
1
end_date
integer
Example:
1
availability
Array nullable
Object
day
integer
Example:
6
month
integer
Example:
11
start_time
string
Example:
13:00
end_time
string
Example:
14:00

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/{id}/targets/timings HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "fixed_period": {
        "start_date": 1,
        "end_date": 1
    },
    "availability": [
        {
            "day": 6,
            "month": 11,
            "start_time": "13:00",
            "end_time": "14:00"
        }
    ]
}

HTTP/1.1 201 Created 
Add Baskets
POST /promotions/{id}/targets/baskets

Path variables

id
string GUID required

The promotion identifier whose target conditions will be updated

Example:
1af94364-b0f2-d656-aed6-bd3e3978cab4

Request body

Object
basket
Object
rules
Object
payment_method_type
string
Enumeration:
CASH
CARD
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
value
number

The basket’s total amount in order to apply the promotion. The promotion is applied if the basket amount is more than or equal tot eh specified amount. The amount is specified in the default currency by default.

quantity
integer

The number of items to be included in the basket in orer to apply the promotion

products
Object
groups
Array
Object
group
string

Name of group

Example:
G1
operator
string

group outer operator

conditions
Array
Object
operator
string
Enumeration:
AND
OR
condition
string

A unique name for the condition

product
Object
id
string
id_type
string
Enumeration:
ID
SKU
FAMILY
BRAND
sku
string
name
string

Product name

quantity
integer
Example:
1
value
number
billing_cycle
Object

Applicable only for termed services

duration
integer
uot
string
contract_period
Object

Applicable only for termed services

duration
integer
uot
string
services
Array

List of services to which a contact must already be subscribed to in order to get the promotion. Only termed services can be specified. Available and applicable only when the basket item is a termed service or a product type of Termed service classification.

Unique items: YES
Object
id
string required

Termed service product identifier

Example:
1af94364-b0f2-d656-aed6-bd3e3978cab4
quantity
number

Contacts should already be subscribed tot he service with at least the specified quantity

Example:
2

Responses

200 200

OK

Body
Object
id
string

Unique identifier for the Promotion’s Basket conditions

Example:
751c28eb-7fe7-4d16-9ee9-1123bbe844cc
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/1af94364-b0f2-d656-aed6-bd3e3978cab4/targets/baskets HTTP/1.1 

Content-Type: application/json

{
    "basket": {
        "rules": {
            "payment_method_type": "CASH",
            "supply_method": "DELIVERY",
            "value": 1,
            "quantity": 1
        },
        "products": { 
            "groups": [
                {
                    "group": "G1",
                    "operator": "",
                    "conditions": [
                        {
                            "operator": "AND",
                            "condition": "",
                            "product": {
                                "id": "",
                                "id_type": "SKU",
                                "sku": "",
                                "name": ""
                            },
                            "quantity": 1,
                            "value": 1,
                            "billing_cycle": {
                                "duration": 1,
                                "uot": ""
                            },
                            "contract_period": {
                                "duration": 1,
                                "uot": ""
                            },
                            "services": [
                                {
                                    "id": "1af94364-b0f2-d656-aed6-bd3e3978cab4",
                                    "quantity": 2
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "751c28eb-7fe7-4d16-9ee9-1123bbe844cc"
}
Offerings

What is offered in a promotions

GET /promotions/{id}/offerings
POST /promotions/{id}/offerings
Get Offerings
GET /promotions/{id}/offerings

Path variables

id
string required

ID of promotion

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

Request OK

Body
Object
offerings
Array
Object
id
string

ID of Offerings

product
Object
id
string

ID of Product

id_type
string
Enumeration:
SKU
FAMILY
BRAND
TYPE
sku
string

Product SKU

name
string

name of product

timing
Array

Applicable only when setting up Item Discounting and only if the discounted products are classified as termed services.

Object
period
Object
duration
integer

For how long the discount will be applied when billing the termed service

Example:
3
uot
string

The unit of time for the promotion

Enumeration:
DAYS
MONTHS
YEARS
type
string

How long the offerring will be applied. Applicable only if the offerring product is a termed service

Enumeration:
ONE_TIME
FOREVER
PERIOD
discount_type
string
Enumeration:
PERCENT
VALUE
amount
number
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/promotions/{id}/offerings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "offerings": [ 
        {
            "id": "",
            "product": {
                "id": "",
                "id_type": "SKU",
                "sku": "",
                "name": ""
            },
            "timing": [
                {
                    "period": {
                        "duration": 3,
                        "uot": "MONTHS"
                    },
                    "type": "ONE_TIME"
                }
            ],
            "discount_type": "PERCENT",
            "amount": 1
        }
    ]
}
Add Offering
POST /promotions/{id}/offerings

Add a number of product offerings that wil receive a discount

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
discount_type
string
Enumeration:
PERCENT
VALUE
amount
number
product
Object
id
string
id_type
string
Enumeration:
SKU
FAMILY
BRAND
TYPE
timing
Array

Applicable only for termed services

Object
type
string required

Shows how many times the promotion’s discount will be applied.

Enumeration:
ONE_TIME

Applied once

FOREVER

Appied forever

PERIOD

Applied onyl for a period of time

Default:
ONE_TIME
period
Object

Period of time during which the promotion is applied. Applicable and required when the offering’s ty eis set to Period

duration
integer required
uot
string required
Enumeration:
DAYS
MONTHS
YEARS

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/promotions/{id}/offerings HTTP/1.1 

Content-Type: application/json

[
    {
        "discount_type": "PERCENT",
        "amount": 1, 
        "product": {
            "id": "",
            "id_type": "BRAND"
        },
        "timing": [
            {
                "type": "ONE_TIME",
                "period": {
                    "duration": 1,
                    "uot": "YEARS"
                }
            }
        ]
    }
]
Order Catalog
POST /order_catalogs
PUT /order_catalogs/{id}
DELETE /order_catalogs/{id}
POST /order_catalogs/{id}/actions
GET /order_catalogs
GET /order_catalogs/{id}
POST /order_catalogs/{id}/media_groups
Create Order Catalogue
POST /order_catalogs

Create a new Order Catalog

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the Order Catalog

description
string

The description of the Order Catalog

display_name
string required

The display name of the Order Catalog

supply_methods
Array required

The supported supply method of the Order Catalog

Example:
DELIVERY
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The order catalog identifier

Example:
CA123456789AQWSXZAQWS1236547896541
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Order Catalogue
PUT /order_catalogs/{id}

Updates an existing Order Catalog

Path variables

id
string GUID required

The order catalog identifier that will be updated

Example:
CA123456789AQWSXZAQWS1236547896541

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the Order Catalog

description
string

The description of the Order Catalog

display_name
string

The display name of the Order Catalog

supply_methods
Array

The supported supply method of the Order Catalog

Example:
DELIVERY
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The order catalog identifier

Example:
CA123456789AQWSXZAQWS1236547896541
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Delete Order Catalogue
DELETE /order_catalogs/{id}

Deletes an existing Order Catalog

Path variables

id
string GUID required

The Order Catalog identifier that will be deleted

Example:
CA123456789AQWSXZAQWS1236547896541

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Perform Order Catalogue Actions
POST /order_catalogs/{id}/actions

Path variables

id
string required

The order catalog identifier whose life cycle state will be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string

The life cycle state that the order catalog will changed into

Enumeration:
ACTIVE
INACTIVE

Responses

200 OK
Body
Object
id
string GUID

The order catalog identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Order Catalogues
GET /order_catalogs

Returns a list of order catalogs of the organisation.

Request parameters

search_value
string optional

Search for an order catalog using its name, dispaly name or description

fulfilled_by
string GUID optional

Retreive order catalogs based on organisation

Example:
7CD9C84FA60F9FE407140E20F707726A
supply_method
string optional

Retrieve order catalog based on supply method

Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The order catalog identifier

name
string

The name of the order catalog

description
string

The description of the order catalog

dislpay_name
string

The dislay name of the order catalog

life_cycle_state
string

The life cycle state that the order catalog

Enumeration:
ACTIVE
INACTIVE
owner
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Get Order Catalogue
GET /order_catalogs/{id}

Retrieve detailed information for a specific order catalog.

Path variables

id
string required

The order catalog identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The order catalog identifier

name
string

The name of the order catalog

description
string

The description of the order catalog

display_name
string

The dislay name of the order catalog

supply_methods
Array

The supported supply methods of the Order Catalog

Example:
DELIVERY
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
life_cycle_state
string

The life cycle state that the order catalog

Enumeration:
ACTIVE
INACTIVE
time_availability
Array

The availability for ordering of the order catalog

Object
day_of_week
string

The ay of the week the Order Catalog is available

Example:
Monday
start_time
string

The start time of the Order Catalog

Example:
09:00
end_time
string

The end time of the Order Catalog

Example:
20:00
accessibility
Object

Defines whether the order catalog is applicable for all organisations under the Business or specific organisations

type
string
Enumeration:
ALL
SPECIFIC
organisations
Array

The organisations (Merchants, Venues) that thos order catalog is applicable for (applicable only if type = SPECIFIC)

Object
id
string

The organisation identifier

name
string

The name of the organisation

creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Order Catalogue Media Groups
POST /order_catalogs/{id}/media_groups

Create a new media group for a specific order catalog

Path variables

id
string GUID required

The order catalog identifer whose media groups will be set

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Notes

MEDIA UPLOAD

Uploading media for an order requires the execution of the following APIs

  1. Create new Media Group
  2. Create Order Catalog Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
7ec65711-8f3b-538c-dec9-8c36ce818382

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/order_catalogs/6A24D2B5E44F44B28451FE021FCAD51E/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "7ec65711-8f3b-538c-dec9-8c36ce818382"
    }
]

HTTP/1.1 200 OK 
Order Catalog Organisations
POST /order_catalogs/{id}/organisations
Set Order Catalogue Organisations
POST /order_catalogs/{id}/organisations

Define the organisations that will have access to utilize the order catalog

Path variables

id
string required

The order catalog identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
accessibility
Object

Defines whether the order catalog is applicable for all organisations under the Business or specific organisations

type
string
Enumeration:
ALL
SPECIFIC
organisations
Array of string GUID

The organisations (Merchants, Venues) that thos order catalog is applicable for (applicable only if type = SPECIFIC)

Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]

Responses

200 OK

The request succeeded

Body
Object
id
string GUID

The order catalog identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Order Catalog Time Availability
POST /order_catalogs/{id}/time_availability
Set Order Catalogue Availability
POST /order_catalogs/{id}/time_availability

Update the order catalog time availability

Path variables

id
string required

The order catalog identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
time_availability
Array

The availability for ordering of the order catalog

Object
day_of_week
string required

The day of the week the Order Catalog is available

Example:
MONDAY
start_time
string required

The start time the Order Catalog

Example:
09:00
end_time
string required

The end time the Order Catalog

Example:
22:00

Responses

200 OK

The request succeedded

Body
Object
id
string GUID

The order catalog identifier

Example:
CA123456789AQWSXZAQWS1236547896541
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Order Catalog Categories
POST /order_catalogs/{id}/categories
PUT /order_catalogs/{id}/categories/{category_id}
POST /order_catalogs/{id}/categories/{category_id}/priorities
DELETE /order_catalogs/{id}/categories/{category_id}
GET /order_catalogs/{id}/categories
POST /order_catalogs/{id}/categories/{category_id}/products
GET /order_catalogs/{id}/categories/{category_id}/products
PUT /order_catalogs/{id}/categories/{category_id}/products/{product_id}
Create Order Catalogue Category
POST /order_catalogs/{id}/categories

Create a new Order Category

Path variables

id
string required

The order catalog identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the category

code
string

The code of the category

description
string

The description of the category

parent_id
string

The parent category of the category

priority
integer

The priority of the order category

Example:
1

Responses

201 Created
Body
Object
id
string GUID

The unique identifier of the newly created order category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Order Catalogue Category
PUT /order_catalogs/{id}/categories/{category_id}

Update an Order Category

Path variables

id
string required

The order catalog identifier

category_id
string required

The order category identifier that will be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the order category

code
string

The code of the order category

description
string

The description of the order category

parent_id
string

The parent of the order category

priority
integer

The priority of the order category

Responses

200 OK
Body
Object
id
string GUID

The unique identifier of the order category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Order Catalogue Category Priority
POST /order_catalogs/{id}/categories/{category_id}/priorities

Update an Order Category priority

Path variables

id
string required

The order catalog identifier

category_id
string required

The order category identifier that priority will be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
priority
integer

The priority of the order category

Example:
3
Delete Order Catalogue Category
DELETE /order_catalogs/{id}/categories/{category_id}

Delete an Order Category

Path variables

id
string required

The order catalog identifier

category_id
string required

The order category identifier that will be deleted

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Order Catalogue Categories
GET /order_catalogs/{id}/categories

Return a list of order categories of an order catalog

Path variables

id
string required

The order catalog identifier

Request parameters

parent_id
string optional

If specified, then all order categories under the parent node will be returned. If not specified, then all root nodes of the tree are returned.

return_all
boolean optional

Returns all order categories of the tree if set to True, ignoring parent_id parameters

Default:
false
include_products
string optional

Returns all products of the category id set to True

Default:
False
search_value
string optional

Search for an order category based on name and description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The order category identifier

name
string

The name of the order identifier

code
string

The code of the order identifier

description
string

The description of the order identifier

child_nodes
integer

The number of child nodes

Example:
2
priority
integer

The priority of the order category

parent
Object

The parent cateogry (if applicable)

id
string GUID

The parent order category identifier

name
string

The name of the parent order category

products
Array

The list of products in the order category (display only if include_products = TRUE)

Object
product
Object
id
string

The product identifier

name
string

The name of the product

sku
string

The SKU of the product

priority
integer

The priority of the product

pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Add/Remove Products from Order Catalogue Category
POST /order_catalogs/{id}/categories/{category_id}/products

Adds or removes products from the Order Catalog

Path variables

id
string required

The order catalog identifier

category_id
string required

The order category identifier that products will be added to/removed from

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
products
Array

The products to be added to the order category

Object
product_id
string GUID

The products to be added to the order category

Example:
"76520515-1a3c-4477-9f6b-92c040f11ad2"
priority
integer

The priority of the product

Example:
1

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Products of Order Catalogue Category
GET /order_catalogs/{id}/categories/{category_id}/products

Retrieve products of an Order Category

Path variables

id
string required

The order catalog identifier

category_id
string required

The order category identifier the products will be retreived from

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
products
Array
Object
product
Object
id
string

The product idenitifer

name
string

The name of the product

sku
string

The sku of the product

priority
integer

The priority of the product

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_catalogs/{id}/order_categories/{category_id}/products HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "7CD9C84FA60F9FE407140E20F707726A",
            "sku": "ABC12345",
            "name": "Base TV"
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Update Priority in Order Catalogue Category
PUT /order_catalogs/{id}/categories/{category_id}/products/{product_id}

Updates the order of the product in the category

Path variables

id
string required
category_id
string required
product_id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
priority
integer

The product priority

Example:
5

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Rewards
GET /offer_restrictions
GET /reward_events
GET /reward_events/{id}/details
Reward Schemes
POST /reward_schemes
PUT /reward_schemes/{id}
GET /reward_schemes
GET /reward_schemes/{id}
POST /reward_schemes/{id}/life_cycle_state
Create Reward Scheme
POST /reward_schemes

Create a new reward scheme

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The reward scheme name

Example:
CRMdotCOM Scheme
description
string nullable

The reward scheme description

Example:
The main reward scheme of CRMdotCOM
sign_up_option
string required

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP

Customers will sign up upon registration automatically

SELF_SIGN_UP

Customers can sign up manually

CLOSE_LOOP_SIGN_UP

Customers can be signed up on a selective and controlled manner (request to join), usually based on a third-party identification or domain specific emails

Default:
SELF_SIGN_UP
sign_up_code
string nullable

Defines whether close loop (controlled) sign ups will be validated based on a third-party identification (external system) or domain specific emails. Required if the sign up option = controlled sign up

Enumeration:
EXTERNAL_SYSTEM
EMAIL_DOMAIN
email_domains
Array nullable

Defines the supported email domains for close loop (controlled) sign ups based on domain. Required when the sign up token = email domain

string
Example:
crm.com
terms_and_conditions
string nullable

The reward scheme terms and conditions

Example:
Only customers that already have CRMdotCOM reward app can join this scheme

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_schemes HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "CRMdotCOM Scheme",
    "description": "The main reward scheme of CRMdotCOM",
    "sign_up_option": "AUTO_SIGN_UP"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Reward Scheme
PUT /reward_schemes/{id}

Update an existing reward scheme

Path variables

id
string GUID required

The reward scheme (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The reward scheme name

Example:
CRMdotCOM Scheme
description
string nullable

The reward scheme description

Example:
The main reward scheme of CRMdotCOM
email_domains
Array nullable

Defines the supported email domains for close loop (controlled) sign ups based on domain. Required on close loop reward schemes and the sign up token = email domain

string
Example:
crm.com
terms_and_conditions
string nullable

The reward scheme terms and conditions

Example:
Only customers that already have CRMdotCOM reward app can join this scheme

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "CRMdotCOM Scheme",
    "description": "The main reward scheme of CRMdotCOM",
    "email_domains": [
        "crm.com"
    ],
    "terms_and_conditions": "Only customers that already have CRMdotCOM reward app can join this scheme"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
List Reward Schemes
GET /reward_schemes

Search for reward schemes

Request parameters

name
string optional

The reward scheme name

Example:
CRMdotCOM
sign_up_option
string optional

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP

Customers will sign up upon registration automatically

SELF_SIGN_UP

Customers can sign up manually

CLOSE_LOOP_SIGN_UP

Customers can be signed up on a selective and controlled manner (request to join), usually based on a third-party identification or domain specific emails

Default:
SELF_SIGN_UP
life_cycle_state
string optional

The reward scheme life cycle state

Enumeration:
ACTIVE
INACTIVE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward scheme name

Example:
CRMdotCOM Scheme
description
string

The reward scheme description

Example:
The main reward scheme of CRMdotCOM
sign_up_option
string

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP

Customers will sign up upon registration automatically

SELF_SIGN_UP

Customers can sign up manually

CLOSE_LOOP_SIGN_UP

Customers can be signed up on a selective and controlled manner (request to join), usually based on a third-party identification or domain specific emails

Default:
SELF_SIGN_UP
life_cycle_state
string

The reward scheme state

Enumeration:
ACTIVE
INACTIVE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/reward_schemes HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "CRMdotCOM Scheme",
            "description": "The main reward scheme of CRMdotCOM",
            "sign_up_option": "CLOSE_LOOP_SIGN_UP"
        }
    ]
}
Get Reward Scheme
GET /reward_schemes/{id}

Get details for a single reward scheme

Path variables

id
string GUID required

The reward scheme (identifier) that will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward scheme name

Example:
CRMdotCOM Scheme
description
string

The reward scheme description

Example:
The main reward scheme of CRMdotCOM
terms_and_conditions
string

The reward scheme terms and conditions

Example:
Only customers that already have CRMdotCOM reward app can join this scheme
sign_up_option
string

Defines how customers can sign up to the reward scheme

Enumeration:
AUTO_SIGN_UP

Customers will sign up upon registration automatically

SELF_SIGN_UP

Customers can sign up manually

CLOSE_LOOP_SIGN_UP

Customers can be signed up on a selective and controlled manner (request to join), usually based on a third-party identification or domain specific emails

Default:
SELF_SIGN_UP
sign_up_code
string

Defines whether close loop (controlled) sign ups will be validated based on a third-party identification (external system) or domain specific emails. Required if the sign up option = controlled sign up

Enumeration:
EXTERNAL_SYSTEM
EMAIL_DOMAIN
email_domains
Array

Defines the supported email domains for close loop (controlled) sign ups based on domain. Required when the sign up token = email domain

string
Example:
crm.com
life_cycle_state
string

The reward scheme state

Enumeration:
ACTIVE
INACTIVE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "name": "CRMdotCOM Scheme",
    "description": "The main reward scheme of CRMdotCOM",
    "sign_up_option": "SELF_SIGN_UP",
    "terms_and_conditions": "Only customers that already have CRMdotCOM reward app can join this scheme"
}
Update Reward Scheme Life Cycle State
POST /reward_schemes/{id}/life_cycle_state

Change the life cycle state of a single reward scheme

Path variables

id
string GUID required

The reward scheme (identifier) whose life cycle state will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string required

The reward scheme state

Enumeration:
ACTIVE
INACTIVE

Responses

200 200

Successful Request

Body
Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_schemes/CAD1E31269B76D7A65ACCE45B2E68DFD/life_cycle_state HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "life_cycle_state": "INACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Reward Offers
POST /reward_offers
PUT /reward_offers/{id}
DELETE /reward_offers/{id}
GET /reward_offers
GET /reward_offers/{id}
POST /reward_offers/{id}/life_cycle_state
GET /reward_offers/{id}/contacts
Create Reward Offer
POST /reward_offers

Create a new reward offer for a specific reward scheme

Notes

Creating an offer with the respective target/award/spend conditions should be made using the following APIs

  • Create Reward Offer: creates the reward offer with key attributes (e.g. name, typr and scheme)

Target Conditions

  • Add Target Contact: offer will be eligible to award a customer event based on specific contact segments (applicable for all offer types)
  • Add Target Organisation: offer will be eligible to award a customer event based on specific organisations that the event took place (applicable only for monetary discount, product discount and happy hour offer types). Timing conditions are applicable for achievement offers, while transation products are applicable for subscription maturity offers as well
  • Add Target Transaction: offer will be eligible to award a customer event based on specific transaction details, such as total purchase amount and purchased products (applicable only for monetary discount, product discount and happy hour offer types)
  • Add Target Evaluation: offer will be eligible to award customers based on a recurring eveluation period, such as lottery (applicable only for thank you gift and lottery offer types)
  • Add Target Referral: offer will be eligible to award a customer (referral) event based specific referral behavior (applicable only for referral offer types)
  • Add Target Customer Events: offer will be eligible to award a customer event based on specific event classification, such as card-linked purchases (applicable only for monetary discount, product discount, happy hour and achievement offer types)
  • Add Target Achievements: offer will be eligible to award a customer event based on specific achievement behavior (applicable only for achievement offer types)
  • Add Target Subscription Maturity: offer will be eligible to award a customer for being loyal customer based on subscription maturity (applicable only for subscription maturity offers)

Award/Spend Conditions

  • Add Award Settings: ability to define award method (amount or percentage based), award restrictions, spend method (instant or deferred), spend conditions and validity/expiration period

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The reward offer name

Example:
10% off any purchase
scheme_id
string GUID required

The reward scheme identifier that the offer will belong to it

Example:
6A24D2B5E44F44B28451FE021FCAD51E
availability
Object required

The offer availability (from-to) dates (whithin this period customers will be awarded)

available_from
integer epoch required

The from date that the offer will be applicable

Example:
1606819297
available_to
integer epoch nullable

The to date that the offer will be applicable to

Example:
1606819297
goal
string required

The offer goal

Enumeration:
ACHIEVEMENT
SPEND
VISITS
MEMBERSHIP
reward_type
string required

The offer type (each goal is related with a type)

Enumeration:
LOTTERY
ACHIEVEMENT
GIFT
DISCOUNT
BUNDLE
SIGNUP
REFER
PROFILE
HAPPYHOUR
REACH_TIER
SUBSCRIPTION_MATURITY
short_description
string nullable

The offer short description

Example:
Enjoy awards with this new offer
long_description
string nullable

The offer long description

Example:
Enjoy awards with this new offer and explore how rewards is good for you
terms_and_conditions
string nullable

The offer terms and conditions

Example:
Applicable for all EU residents
is_featured
boolean nullable

Defines whether the reward offer will be featured (ordered higher) in customer facing clients

Default:
false
Example:
false

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_offers HTTP/1.1 

Content-Type: application/json

{
    "name": "10% off any purchase",
    "short_description": "",
    "long_description": "",
    "scheme": {
        "id": "622175bf-03b0-4e9e-9df9-adf85080a889"
    },
    "availability": {
        "available_from": 1,
        "available_to": 1,
        "is_recurring": true
    },
    "goal": "VISITS",
    "reward_type": "MATURITY",
    "tags": [
        {
            "id": "guid"
        }
    ]
}

HTTP/1.1 201 Created 
Update Reward Offer
PUT /reward_offers/{id}

Update an existing reward offer

Path variables

id
string GUID required

The reward offer (identifier) that will be updated

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The offer name

Example:
10% off any purchase
availability
Object nullable

The offer availability (from-to) dates (whithin this period customers will be awarded)

available_from
integer epoch required

The from date that the offer will be applicable

Example:
1606819139
available_to
integer epoch nullable

The to date that the offer will be applicable to

Example:
1606819139
short_description
string nullable

The offer short description

Example:
Reward Offer Short Description
long_description
string nullable

The offer long description

Example:
Reward Offer Long Description
terms_and_conditions
string nullable

Terms and Conditions

Example:
Applicable for all EU residents
is_featured
boolean nullable

Defines whether the reward offer will be featured (ordered higher) in customer facing clients

Default:
false
Example:
false

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "10% off any purchase",
    "tags": [
        "6A24D2B5E44F44B28451FE021FCAD51E"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E"
}
Delete Reward Offer
DELETE /reward_offers/{id}

Delete an existing reward offer

Path variables

id
string GUID required

The reward offer (identifier) that will be deleted

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Reward Offers
GET /reward_offers

Search for reward offers

Request parameters

search_value
string optional

The value of the search (case insensitive) across name

Example:
Increase Visits
name
string optional

Search by reward offer name

Example:
1% cashback on all products
life_cycle_state
string optional

Filter by life cycle state

Enumeration:
ACTIVE
INACTIVE
EXPIRED
schemes
array of string optional

Filter based on scheme (defaults to All)

Collection format: csv
Unique items: YES
organisations
array of string optional

Select by organisations ( merchants ), by default the token / secret key will be used to identify the top level of the Network that offers are created for.

Collection format: csv
Unique items: YES
owned_by
array of string optional

Filters organisations (identifiers) whether offers are owned by them

Collection format: csv
offer_types
array of Reward Offer Type (enum) optional

Filter based on offer type

Collection format: csv
Unique items: YES
is_featured
boolean optional

Filter based on whether the reward offers will be featured (ordered higher) in customer facing clients

Example:
false
approval_state
string optional

Filter based on approval requests applied on such offers

Enumeration:
APPROVED
REJECTED
PENDING_APPROVAL
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_approvals
boolean optional

Defines whether approval requests information should be retrieved or not

Example:
true
approval_state
string optional

Filter based on approval request state

Enumeration:
PENDING
APPROVED
REJECTED

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The reward offer identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The reward offer name

Example:
10% off any purchase
short_description
string

Short description used in Mobile or other APP experiences

Example:
Reward Offer Short Description
long_description
string

The reward offer description

Example:
Reward Offer Long Description
scheme
Object

The reward scheme that the offer belongs to

id
string GUID

The reward scheme identifier

Example:
622175bf-03b0-4e9e-9df9-adf85080a889
name
string

The reward scheme name

Example:
Coffee Scheme
goal
string

The offer goal

Enumeration:
ACHIEVEMENT
SPEND
VISITS
MEMBERSHIP
reward_type
string

The offer type (each goal is related with a type)

Enumeration:
LOTTERY
ACHIEVEMENT
GIFT
DISCOUNT
BUNDLE
SIGNUP
REFER
PROFILE
HAPPYHOUR
REACH_TIER
SUBSCRIPTION_MATURITY
availability
Object

The offer availability (from-to) dates (whithin this period customers will be awarded)

available_from
integer epoch

The date of start period for offer

Example:
1606819297
available_to
integer epoch

The date of end period for offer

Example:
1606819297
tags
Array

The tags associated to the reward offer

Object
id
string GUID

The tag identifier

Example:
wer-3rwefsf2rf-wef-2f-wef-2r
name
string

The tag name

Example:
Seasonal
life_cycle_state
string

The offer life cycle state

Enumeration:
ACTIVE
INACTIVE
EXPIRED
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
is_featured
boolean

Defines whether the reward offer will be featured (ordered higher) in customer facing clients

Example:
false
owner
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
approvals
Object

Details about the latest requested approval(s)

state
string

The approval request state

Enumeration:
PENDING
APPROVED
REJECTED
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reward_offers HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "10% off any purchase",
            "short_description": "Reward Offer Short Description",
            "long_description": "Reward Offer Long Description",
            "scheme": {
                "id": "622175bf-03b0-4e9e-9df9-adf85080a889",
                "name": "Coffee Scheme"
            },
            "goal": "SPEND",
            "reward_type": "KPI",
            "availability": {
                "available_from": 1606819297,
                "available_to": 1606819297
            },
            "tags": [
                {
                    "id": "wer-3rwefsf2rf-wef-2f-wef-2r",
                    "name": "Seasonal"
                }
            ],
            "life_cycle_state": "PENDING_APPROVAL",
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "MARKETING",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ],
            "is_featured": "false",
            "owner": {
                "id": "0d943fdb-c30a-924a-a1ee-d7dbdff99cc5",
                "name": "CRM.COM"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Reward Offer
GET /reward_offers/{id}

Get details for a single reward offer

Path variables

id
string GUID required

The reward offer (identifier) that will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

Name of Offer Used internally

Example:
10% off any purchase
scheme
Object

The reward scheme that the offer belongs to

id
string GUID

The reward scheme identifier

Example:
622175bf-03b0-4e9e-9df9-adf85080a889
name
string

The reward scheme name

Example:
Coffee Scheme
goal
string

The offer goal

Enumeration:
ACHIEVEMENT
SPEND
VISITS
MEMBERSHIP
reward_type
string

The offer type (each goal is related with a type)

Enumeration:
LOTTERY
ACHIEVEMENT
GIFT
DISCOUNT
BUNDLE
SIGNUP
REFER
PROFILE
HAPPYHOUR
REACH_TIER
SUBSCRIPTION_MATURITY
short_description
string

The offer short description

Example:
Reward Offer Short Description
long_description
string

The offer long description

Example:
Reward Offer Long Description
terms_and_conditions
string

The offer terms and conditions

Example:
Applicable for all EU residents
availability
Object

The offer availability (from-to) dates (whithin this period customers will be awarded)

available_from
integer epoch

The from date that the offer will be applicable

Example:
1606819297
available_to
integer epoch

The to date that the offer will be applicable to

Example:
1606819297
tags
Array

The tags associated with the reward offer

Object
id
string GUID

The tag identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The tag name

Example:
Seasonal
life_cycle_state
string

The offer life cycle state

Enumeration:
ACTIVE
INACTIVE
EXPIRED
media_groups
Array

Media groups information (multiple can be supported)

Object
id
string GUID

The media group identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The media group name

Example:
Marketing Media
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
is_featured
boolean

Defines whether the reward offer will be featured (ordered higher) in customer facing clients

Example:
false
owner
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
Example 1
GET https://sandbox.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
    "name": "10% off any purchase",
    "scheme": {
        "id": "622175bf-03b0-4e9e-9df9-adf85080a889",
        "name": "Coffee Scheme"
    },
    "goal": "SPEND",
    "reward_type": "APPLICATION",
    "short_description": "Reward Offer Short Description",
    "long_description": "Reward Offer Long Description",
    "terms_and_conditions": "Applicable for all EU residents",
    "availability": {
        "available_from": 1606819297,
        "available_to": 1606819297
    },
    "tags": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Seasonal"
        }
    ],
    "life_cycle_state": "EXPIRED",
    "media_groups": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Marketing Media",
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "usage_type": "PROFILEIMAGE",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/logo.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                        }
                    ]
                }
            ]
        }
    ],
    "is_featured": "false",
    "owner": {
        "id": "20095138-cdec-0743-7ac1-d0aeb68d553f",
        "name": "Best Coffee"
    }
}
Update Reward Offer Life Cycle State
POST /reward_offers/{id}/life_cycle_state

Change the life cycle state of a single reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose life cycle state will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string required

The life cycle state that the reward offer will changed into

Enumeration:
ACTIVE
INACTIVE

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_offers/CAD1E31269B76D7A65ACCE45B2E68DFD/life_cycle_state HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "life_cycle_state": "ACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Get Awarded Contacts
GET /reward_offers/{id}/contacts

Returns awarded contacts of a reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose awarded contacts will be returned

Example:
9f2e66af-d42d-4c15-9346-7e2cc0a89f6e

Notes

Applicable only for Lottery offer types

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The contact’s unique identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The contact’s name (full name for Persons, company name for Companies)

Example:
John Smith
code
string

The contact’s code

Example:
0049304938571623
date
integer epoch

The date that the award was provided

Example:
1606376717
award_amount
number

The awarded amount

Example:
9.99
award_product
Object

The awarded product (free product)

type
string

The awarded product type

Enumeration:
SKU
BRAND
TYPE
FAMILY
id
string GUID

The awarded product identifier

Example:
5ffe7466-aad3-11bb-1617-3c07a6db75d4
name
string

The awarded product name

Example:
Coffee
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reward_offers/9f2e66af-d42d-4c15-9346-7e2cc0a89f6e/contacts HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "John Smith",
            "code": "0049304938571623",
            "award_amount": 9.99,
            "date": 1606376717
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Target Conditions
POST /reward_offers/{id}/targets/contacts
POST /reward_offers/{id}/targets/organisations
POST /reward_offers/{id}/targets/transactions
POST /reward_offers/{id}/targets/evaluations
POST /reward_offers/{id}/targets/referrals
POST /reward_offers/{id}/targets/events
POST /reward_offers/{id}/targets/achievements
POST /reward_offers/{id}/targets/maturity
GET /reward_offers/{id}/targets
Set Target Contact
POST /reward_offers/{id}/targets/contacts

Set the contact target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose contact target conditions will be updated

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Notes

Applicable for all reward offer types, excluding sign up

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_segments
Array nullable

The contact segments that will be targeted by the offer

Unique items: YES
string GUID
Example:
6A24D2B5E44F44B28451FE021FCAD51E
profile_completeness
Array nullable

Customers that complete their profile

Object
information
string required

The profile information that is provided

Enumeration:
BIRTHDATE
NAMEDAY
ADDRESS
EMAIL
PHONE
GENDER
PHONE_VERIFICATION

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E/targets/contacts HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "contact_segments": [
        "6A24D2B5E44F44B28451FE021FCAD51E"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Organisation
POST /reward_offers/{id}/targets/organisations

Set the location (organisation) target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose location target conditions will be set

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Notes

Applicable only for Product Discount, Monetary Discount and Happy Hour reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
organisations
Array nullable

The organisations that will be targeted by this offer

Unique items: YES
string GUID
Example:
6A24D2B5E44F44B28451FE021FCAD51E
countries
Array of string nullable

The countries (code) that will be targeted by this offer

Unique items: YES
Example:
CYP

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E/targets/organisations HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "organisations": [
        "6A24D2B5E44F44B28451FE021FCAD51E"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Transaction
POST /reward_offers/{id}/targets/transactions

Set the transaction (purchase) target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose transaction target conditions will be updated

Example:
1af94364-b0f2-d656-aed6-bd3e3978cab4

Notes

Target Transactions conditions are applicable for Product Discount, Monetary Discount and Happy Hour reward offer types

Timing conditions are applicable for Achievement offer types

Product conditions (w/o cumulative) are applicable for Subscription Maturity

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
transactions
Object

List conditions on transaction

transaction_total
Object

Total transaction conditions

currency
string

The transaction currency

Example:
EUR
transaction_value
number

The transaction value

Example:
10.99
unit_of_time
string

The period for which cumulative will be performed

Enumeration:
DAY
WEEK
MONTH
YEAR
OVERALL
operator
string

The condition operator

Example:
AND
products
Array

Product conditions

Object
groups
Array

List of product group conditions

Object
group
string

The group name

Example:
G1
operator
string

The group operator

Example:
AND
conditions
Array

Details about the group conditions

Object
condition
string

The condition name

Example:
C1
id
string GUID

the product condition (sku/brand/etc) identifier

Example:
46332fda-8f84-4b6a-bd46-f00e48445b82
id_type
string

The condition type

Enumeration:
SKU
BRAND
FAMILY
name
string

The condition name

Example:
Product conditions
qty
integer

The product condition quantity

Example:
1
value
number

The product condition value

Example:
2.5
currency
string

The currency for product value

Example:
EUR
unit_of_time
string

The period for which cumulative will be performed

Enumeration:
DAY
WEEK
MONTH
YEAR
OVERALL
operator
string

The condition operator

Example:
AND
timings
Object

Timing Conditions

is_birthday
boolean

Offer targets condition on customer birthday

Example:
true
is_nameday
boolean

Offer targets condition on customer nameday

Example:
true
days_before
number

Offer will target X days before birthday/nameday

Example:
1
days_after
number

Offer will target X days after birthday/nameday

Example:
1
availability
Array

List of days/times that offer will target

Object
month
integer

The availability month

Example:
1
day
integer

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

Example:
1
start_time
string

The availability start time

Example:
19:00
end_time
string

The availability end time

Example:
21:00

Responses

200 OK
Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/1af94364-b0f2-d656-aed6-bd3e3978cab4/targets/transactions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "transactions": {
        "transaction_total": {
            "currency": "EUR",
            "transaction_value": 10.99,
            "unit_of_time": "WEEK",
            "operator": "AND"
        },
        "products": [
            {
                "groups": [
                    {
                        "group": "G1",
                        "operator": "AND",
                        "conditions": [
                            {
                                "condition": "C1",
                                "id": "46332fda-8f84-4b6a-bd46-f00e48445b82",
                                "id_type": "SKU",
                                "name": "Product conditions",
                                "qty": 1,
                                "value": 2.5,
                                "currency": "EUR",
                                "unit_of_time": "YEAR",
                                "operator": "AND"
                            }
                        ]
                    }
                ]
            }
        ],
        "timings": {
            "is_birthday": true,
            "is_nameday": true,
            "days_before": 1,
            "days_after": 1,
            "availability": [
                {
                    "month": 1,
                    "day": 1,
                    "start_time": "19:00",
                    "end_time": "21:00"
                }
            ]
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Evaluation
POST /reward_offers/{id}/targets/evaluations

Set the evaluation (timings) target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose evaluation target conditions will be updated

Example:
71688194-e07f-4010-acd1-b8dec6d19a7a

Notes

Applicable for Lottery and Thank You Gift reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
timings
Object nullable

Details about the evaluation time

start_date
integer epoch required

The date that the offer will be evaluaed (just once)

Example:
1592317898
frequency
string required nullable

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
acd2d760-a059-6582-adb9-f1cf2982ef65
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/71688194-e07f-4010-acd1-b8dec6d19a7a/targets/evaluations HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "timings": {
        "start_date": 1592317898,
        "frequency": "0 0 12 * * ?"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Referral
POST /reward_offers/{id}/targets/referrals

Set the referral target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose target conditions will be updated

Example:
71688194-e07f-4010-acd1-b8dec6d19a7a

Notes

Applicable only for Referral reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

Defines what is required to award such referral

Enumeration:
AFTER_PURCHASE

Award will be provided after the referred customer registers and makes a purchases

ON_REGISTRATION

Award will be provided after the referred customers registers

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/reward_offers/71688194-e07f-4010-acd1-b8dec6d19a7a/targets/referrals HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "action": "ON_REGISTRATION"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Customer Events
POST /reward_offers/{id}/targets/events

Set the event (classifications) target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose target conditions will be updated

Example:
71688194-e07f-4010-acd1-b8dec6d19a7a

Notes

Applicable only for Product Discount, Monetary Discount, Happy Hour and Achievement reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
event_classifications
Array GUID

Defines what is required to award such referral

Unique items: YES
Example:
5d660d3a-80bb-1925-ef77-e29fd4bbfc7b
string GUID
Example:
5d660d3a-80bb-1925-ef77-e29fd4bbfc7b

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/71688194-e07f-4010-acd1-b8dec6d19a7a/targets/events HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "event_classifications": [
        "5d660d3a-80bb-1925-ef77-e29fd4bbfc7b"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Achievements
POST /reward_offers/{id}/targets/achievements

Set the achievement target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose target conditions will be updated

Example:
71688194-e07f-4010-acd1-b8dec6d19a7a

Notes

Applicable only for Achievement reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
monetary
Object nullable

Defines the monetary (amount) conditions

currency
string required

The transaction currency

Example:
EUR
value
number required

The transaction value

Example:
12.11
operator
string required

The transaction value operator that should be met

Enumeration:
EQUAL

Value should be equal to the configured one

EQUAL_GREATER

Value should be greater or equal to the configured one

EQUAL_LESS

Value should be greater or less to the configured one

LESS

Value should be less to the configured one

GREATER

Value should be greater to the configured one

Responses

200 OK
Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/71688194-e07f-4010-acd1-b8dec6d19a7a/targets/achievements HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "cumulative": {
        "unit_of_time": "WEEK",
        "value": 12
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "acd2d760-a059-6582-adb9-f1cf2982ef65"
}
Set Target Subscription Maturity
POST /reward_offers/{id}/targets/maturity

Set the maturity target conditions for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose target conditions will be updated

Example:
71688194-e07f-4010-acd1-b8dec6d19a7a

Notes

Applicable only for Subscription Maturity reward offer types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
maturity
Object nullable

Defines what is required to award subscription maturity

unit_of_time
string

The period for subscription maturity check

Enumeration:
MONTH
YEAR
value
integer nullable

The maturity period

Default:
12
Example:
12

Responses

200 OK
Body
Object
id
string GUID

The reward offer identifier

Example:
b99d5c5f-42a8-21da-b1f7-7c3398c110a7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/71688194-e07f-4010-acd1-b8dec6d19a7a/targets/maturity HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "maturity": {
        "unit_of_time": "MONTH",
        "value": 12
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "b99d5c5f-42a8-21da-b1f7-7c3398c110a7"
}
Get Target Conditions
GET /reward_offers/{id}/targets

Retrieves the offer target conditions, such as contact segments

Path variables

id
string GUID required

The reward offer (identifier) whose target conditions will be retrieved

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
contact_segments
Array

Details about contact segment conditions

Object
id
string GUID

The segment identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The segment name

Example:
VIP Customers
description
string

The segment description

Example:
All customers that are classified as VIP
size
integer

The number of results for that segment

Example:
112
profile_completeness
Array

Details about profile completeness conditions

Object
information
string

The profile information that is provided

Enumeration:
BIRTHDATE
NAMEDAY
ADDRESS
EMAIL
PHONE
GENDER
PHONE_VERIFICATION
organisations
Array

Details about location conditions based on organisation

Object
id
string GUID

The organisation identifier

Example:
234234234234-23423sdfs-324234sfsf
type
string

The organisation type

Enumeration:
MERCHANT
VENUE
name
string

The organisation name

Example:
Bravo Bakery
locations
Array

The organisation locations

Object

Information about the organisation’s location

name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
countries
Array

Details about location conditions based on countries

Object
country
string

The country (code) that is targetted

Example:
CYP
transactions
Object

Details about transaction conditions

transaction_total
Object

Transaction (total) Conditions

currency
string

The transaction currency

Example:
EUR
transaction_value
integer

The transaction value

Example:
50
unit_of_time
string

The period for which cumulative will be performed

Enumeration:
DAY
WEEK
MONTH
YEAR
OVERALL
operator
string

Condition operator

Example:
AND
products
Array

Product Conditions

Object
groups
Array

A list of group conditions

Object
group
string

The group name

Example:
G1
operator
string

The group condition operator

Example:
AND
conditions
Array

List group conditions

Object
condition
string

The condition name

Example:
C1
id
string GUID

The condition identifier

Example:
46332fda-8f84-4b6a-bd46-f00e48445b82
id_type
string

The condition type

Enumeration:
SKU
BRAND
FAMILY
name
string

The product condition (sku/brand/family) name

Example:
Coffee
description
string

The product condition (sku/brand/family) description

Example:
Cold Drinks
qty
integer

The product condition quantity

Example:
1
value
number

The product condition value

Example:
2.5
currency
string

The currency code

Example:
EUR
unit_of_time
string

The period for which cumulative will be performed

Enumeration:
DAY
WEEK
MONTH
YEAR
OVERALL
operator
string

The condition operator

Example:
AND
timings
Object

Timing Conditions

is_birthday
boolean

Offer targets condition on customer birthday

Example:
true
is_nameday
boolean

Offer targets condition on customer nameday

Example:
true
days_before
number

Offer will target X days before birthday/nameday

Example:
1
days_after
number

Offer will target X days after birthday/nameday

Example:
1
availability
Array

List of days/times that offer will target

Object
month
integer

The availability month

Example:
1
day
integer

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

Example:
1
start_time
string

The availability start time

Example:
19:00
end_time
string

The availability end time

Example:
21:00
evaluation
Object

Details about evaluation

timings
Object

DEtails about the evaluation time

start_date
integer epoch

The date that the offer will be evaluaed (just once)

Example:
1592317898
frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
passes
Array

Details about passes (types) conditions

Object

Details about the related type

id
string GUID

The type identifier

Example:
c01ecd1b-ff1e-35c2-7236-59ae20339c78
name
string

The type name

Example:
Internal Transaction
referrals
Object

Details about referral conditions

action
string

Defines what is required to award such referral

Enumeration:
AFTER_PURCHASE

Award will be provided after the referred customer registers and makes a purchases

ON_REGISTRATION

Award will be provided after the referred customers registers

event_classifications
Array

Details about the customer event classifications conditions

Object
id
string GUID

The customer event classification identifier

Example:
e262dba7-46d7-d4a2-4ddc-09177029ac1f
name
string

The customer event classification name

Example:
Delivery
achievements
Object

Details about achievement conditions

monetary
Object

Defines the monetary (amount) conditions

currency
string

The transaction currency

value
number

The transaction value

Example:
12.11
operator
string

The transaction value operator that should be met

Enumeration:
EQUAL

Value should be equal to the configured one

EQUAL_GREATER

Value should be greater or equal to the configured one

EQUAL_LESS

Value should be greater or less to the configured one

LESS

Value should be less to the configured one

GREATER

Value should be greater to the configured one

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E/targets HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "contact_segments": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "VIP Customers",
            "description": "All customers that are classified as VIP",
            "size": 112
        }
    ],
    "social_actions": [
        {
            "platform": "TRIPADVISOR",
            "action": "SHARE"
        }
    ],
    "profile_completeness": [
        {
            "information": "PHONE"
        }
    ],
    "organisations": [
        {
            "id": "234234234234-23423sdfs-324234sfsf",
            "type": "MERCHANT",
            "name": "Bravo Bakery",
            "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": "CYP",
                    "care_of": "Main",
                    "lat": "35.157115",
                    "lon": "33.313719",
                    "googleplaceid": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ]
        }
    ],
    "countries": [
        {
            "country": "CYP"
        }
    ],
    "transactions": {
        "transaction_total": {
            "currency": "EUR",
            "transaction_value": 50,
            "period": 12,
            "operator": "AND"
        },
        "products": [
            {
                "groups": [
                    {
                        "group": "G1",
                        "operator": "AND",
                        "conditions": [
                            {
                                "condition": "C1",
                                "id": "46332fda-8f84-4b6a-bd46-f00e48445b82",
                                "id_type": "BRAND",
                                "name": "Coffee",
                                "description": "Cold Drinks",
                                "qty": 1,
                                "value": 2.5,
                                "currency": "EUR",
                                "period": 1,
                                "operator": "AND"
                            }
                        ]
                    }
                ]
            }
        ],
        "timings": {
            "is_birthday": true,
            "is_nameday": true,
            "days_before": 1,
            "days_after": 1,
            "availability": [
                {
                    "month": 1,
                    "day": 1,
                    "start_time": "19:00",
                    "end_time": "21:00"
                }
            ]
        }
    },
    "evaluation": {
        "timings": {
            "start_date": 1592317898,
            "frequency": "0 0 12 * * ?"
        }
    },
    "passes": [
        {
            "id": "51cdb8c5-d868-ec3a-ec3b-0e9a4eca53d0",
            "name": "Birthday Pass"
        }
    ],
    "referrals": {
        "action": "AFTER_PURCHASE"
    },
    "event_classifications": [
        {
            "id": "e262dba7-46d7-d4a2-4ddc-09177029ac1f",
            "name": "Delivery"
        }
    ]
}
Award Conditions
POST /reward_offers/{id}/awards
GET /reward_offers/{id}/awards
Set Award Settings
POST /reward_offers/{id}/awards

Set/Update settings to define the award amount, award restrictions and spend method of the reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose award details will be set

Example:
ce3e9354-9d22-b956-af24-f971abb44bbb

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
awards
Array required

Award Settings

Object
amount
number required

The award amount

Example:
10.99
currency_type
string nullable

The award currency type

Enumeration:
DEFAULT
VIRTUAL

Roadmap

amount_type
string

The award type

Enumeration:
FIXED

Award will be based on a fixed amount

PERCENTAGE

Award will be based on a percentage amount

QTY

Award will be differentiated based on item quantity

quantity
number nullable

Is the award based on a Unit of Measure I.e Litres.

Example:
1
products
Object nullable

Award Product Conditions

id
string GUID required

The product condition identifier (can be the identifier of a product, brand or family)

Example:
2df28809-72ff-379e-50e9-93873f06bbd9
id_type
string

The product condition type

Enumeration:
SKU

Product SKU

FAMILY

Product Family

BRAND

Product Brand

TYPE

Product Type

restrictions
Object required

Award Restrictions

total_winners
integer nullable

The number of customers that can win a lotter draw

Default:
1
Example:
2
total_customers
integer nullable

The total number of customers that can be awarded. After that the offer (still active) will not award anymore customers

Example:
1
amount_cap
number nullable

The maximum awarded amount that can be provided (applicable when award is based on percentage)

Example:
99.99
frequency_cap
Object nullable

Restrict awards provided by the offer to a maximum threshold, such as 1 per day

frequency
number required

How many Times an Award can be given

Example:
1
period
integer required

During the Time Period

Example:
1
period_unit
string nullable

Unit of Time of Period

Enumeration:
DAY
MONTH
YEAR
spend_settings
Object required

Details of the spend conditons

spend_method
string

Defines how award will be spent

Enumeration:
INSTANT
ON_REQUESST
id
string GUID required nullable

The spend condition identifier (required only if spend method is on_requesr)

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Responses

200 OK
Body
Object
id
string GUID

The reward offer identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E/awards HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "awards": [
        {
            "amount": 10.99,
            "currency_type": "VIRTUAL",
            "amount_type": "PERCENTAGE",
            "quantity": 1,
            "products": 
                {
                    "id": "6A24D2B5E44F44B28451FE021FCAD51E",
                    "id_type": "BRAND"
                }
            
        }
    ],
    "validity": {
        "validity_type": "PERIOD",
        "valid_date": 1590474228,
        "period": 1,
        "period_unit": "MONTH"
    },
    "expiration": {
        "expiration_type": "PERIOD",
        "specific_date": 1590474228,
        "period": 1,
        "period_unit": "DAY"
    },
    "restrictions": {
        "total_winners": 2,
        "total_customers": 1,
        "amount_cap": 99.99,
        "frequency_cap": {
            "frequency": 1,
            "period": 1,
            "period_unit": "YEAR"
        },
        "spend_settings": {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "spend_method": "ON_REQUESST"
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E"
}
Get Award Settings
GET /reward_offers/{id}/awards

Retrieve the award settings for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifier) whose award details will be retrieved

Example:
ce3e9354-9d22-b956-af24-f971abb44bbb

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
awards
Array

Award Settings

Object
amount_type
string

The award type

Enumeration:
FIXED

Award will be based on a fixed amount

PERCENTAGE

Award will be based on a percentage amount

QTY

Award will be differentiated based on item quantity

currency_type
string

The award currency

Enumeration:
DEFAULT
VIRTUAL

Roadmap

amount
number

The award amount

Example:
10.99
quantity
number

The product quantity ration for award

Example:
1
products
Object

Details about the award products

id
string GUID

The product condition identifier (can be the identifier of a product, brand or family)

Example:
e2bc1ca2-264c-3f12-bbaf-a7ba4bb099e0
id_type
string

The product condition type

Enumeration:
SKU

Product SKU

FAMILY

Product Family

BRAND

Product Brand

TYPE

Product Type

name
string

The product condition name (can be the name of a product, brand, category or family)

Example:
SKU00001
description
string

The product condition description (can be the description of a product, brand, category or family)

Example:
Coffee Latte
restrictions
Object

Award Restrictions

total_winners
integer

The number of customers that can win a lotter draw

Example:
2
total_customers
integer

The total number of customers that can get the award

Example:
1
amount_cap
number

The maximum amount that can be provided by a offer that awards based on percentage

Example:
1345.23
frequency_cap
Object

Details about the frequency that customers can get the award

frequency
integer

The frequency of the award

Example:
1
period
integer

The frequency period

Example:
12
period_unit
string

Unit of Time of Period

Enumeration:
DAY
MONTH
YEAR
spend_settings
Object

Details of the spend conditons

id
string GUID

The spend condition identifier

Example:
dc01f65b-a482-48f1-9fda-c163df72f28f
name
string

The spend condition name

Example:
Spend Anywhere
spend_method
string

Defines how award will be spent

Enumeration:
INSTANT
ON_REQUESST
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/reward_offers/{id}/awards HTTP/1.1 

Content-Type: application/json

{
    "awards": [
        {
            "amount": 1.5,
            "currency": "DEFAULT",
            "amount_type": "PERCENTAGE",
            "products": {
                "id": "guid_coffee_family",
                "id_type": "FAMILY",
                "name" : "All Coffee Products"
            }},
            {
            "amount": 2.0,
            "currency": "DEFAULT",
            "amount_type": "PERCENTAGE",
            "products": {
                "id": "guid_smoothie_family",
                "id_type": "FAMILY",
                "name" : "All Smoothie Products"
            }
        }
    ],
    "expiration": {
        "expiration_type": "PERIOD",
        "period": 90,
        "period_unit": "DAYS"
    }
}
Media Group
POST /reward_offers/{id}/media_groups
Reward Offer Media Groups
POST /reward_offers/{id}/media_groups

Create a new media group for a specific reward offer

Path variables

id
string GUID required

The reward offer (identifer) whose media groups will be set

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Notes

MEDIA UPLOAD

Uploading media for a reward offer requires the execution of the following APIs

  1. Create new Media Group
  2. Create Reward Offer Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
70b85ee1-c291-634d-2ddf-1f39c42e4f42

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/reward_offers/6A24D2B5E44F44B28451FE021FCAD51E/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "70b85ee1-c291-634d-2ddf-1f39c42e4f42"
    }
]

HTTP/1.1 200 OK 
Merchants
List of Participating Merchants
GET /merchants

Search for organisations with reward commercial terms

Notes

Retrieves only the organisations (Businesses, Merchants, Service Providers) with non-blocked reward commercial terms

Request parameters

include_schemes
boolean optional

Defines whether reward scheme information should be retrieved

Example:
true
include_venues
boolean optional

Defines whether venue information should be retrieved

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Delicious Burger
is_parent
boolean

Indicates whether the organisation has no other child organisations

Example:
true
taps
Array

Information about the transaction acquiring points

Object
id
string GUID

The tap identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The tap name

Example:
T123456
code
string

The tap code

Example:
T123
tap_type
string

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
string

Optional specification of external reference

Enumeration:
JCC
TWINSOFT
ALOHA
WIFI_PLATFORM
is_active
boolean

Defines whethe tap is active or not

Example:
false
reward_schemes
Array

Information about the reward schemes that the organisation participates (retrieved only if requested)

Object
id
string GUID

The reward scheme identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The reward scheme name

Example:
MyCompany Scheme
venues
Array

Details about the venues of the merchant (retrieved only if requested)

Object
id
string GUID

The name organisation identifier

Example:
01f18103-75e0-10b1-31c1-74523f240911
name
string

The venue organisation name

Example:
Delicious Burger Nicosia
taps
Array

Details about the venue organisation transaction acquiring points

Object
id
string GUID

The transaction acquiring point identifier

Example:
01f18103-75e0-10b1-31c1-74523f240955
name
string

The transaction acquiring point name

Example:
Transaction Acquirer
code
string

The transaction acquiring point code

Example:
1234
tap_type
string

The transaction acquiring point type

Enumeration:
EXTERNAL_REF
POS
PRINTER_RECEIPT
CARD_TERMINAL
external_type
string

Optional specification of external reference

Enumeration:
JCC
TWINSOFT
ALOHA
WIFI_PLATFORM
is_active
boolean

Defines whethe tap is active or not

Example:
false
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/merchants HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Delicious Burger",
            "is_parent": true,
            "taps": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "T123456",
                    "code": "T123"
                }
            ],
            "reward_schemes": [
                {
                    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                    "name": "MyCompany Scheme"
                }
            ],
            "venues": [
                {
                    "id": "01f18103-75e0-10b1-31c1-74523f240911",
                    "name": "Delicious Burger Nicosia",
                    "taps": [
                        {
                            "id": "01f18103-75e0-10b1-31c1-74523f240955",
                            "name": "Transaction Acquirer",
                            "code": "1234"
                        }
                    ]
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Reward Offers Restrictions
GET /offer_restrictions

Retrieve the allowed reward offer type(s) and spend method(s) that can be used on reward offer creation

Notes

CORE BEHAVIOR

Service Owner restrictions will be applied on all Businesses (and their Merchants/Service Providers) that share the same contact registry, while Business restrictions (that have their own contact registry) will be applied only on their Merchants/Service Providers.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
allowed_offer_types
Array

Defines the offer types that will be allowed to be created

Unique items: YES
Example:
[
    "MONETARY_DISCOUNT"
]
string
Example:
MONETARY_DISCOUNT
allowed_spend_methods
Array

Defines which spend methods are allowed

Unique items: YES
string
Enumeration:
INSTANT
ON_REQUEST
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/offer_restrictions HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "allowed_offer_types": [
        "MONETARY_DISCOUNT"
    ],
    "allowed_spend_methods": [
        "INSTANT"
    ]
}
List Reward Events
GET /reward_events

Retrieve all reward events

Request parameters

event
string optional

The type of events to filter

Enumeration:
PURCHASE
REFERRAL
LOTTERY
THANK_YOU
CONTACT_REGISTRATION
PROFILE_COMPLETION
ACHIEVEMENT
AD_HOC_RETURN
REACH_TIER
SUBSCRIPTION_MATURITY
performed_date
integer epoch optional

Filter based on the performed date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. performed_on[gte]=1618395497&performed_on[lt]=1618395497).

Example:
11614942379
performed_on
string optional

Filter based on the performed date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. performed_on[gte]=1618395497&performed_on[lt]=1618395497).

Enumeration:
performed_on[gt]

Returns results where the performed date is greater than this value

performed_on[gte]

Returns results where the performed date is greater than or equal to this value

performed_on[lt]

Returns results where the performed date is less than this value

performed_on[lte]

Returns results where the performed date is less then or equal to this value

total_amount
string optional

Filter based on the total amount, which may fall within a given amount range. The value can be a string with an amount in numeric format. Each option must also include an operator. Use up to two options based on the required search (e.g. total_amount[gte]=12.99&total_amount[lt]=99.99).

Enumeration:
total_amount[gt]

Returns results where the total amount is greater than this value

total_amount[gte]

Returns results where the total amount is greater than or equal to this value

total_amount[lt]

Returns results where the total amount is less than this value

total_amount[lte]

Returns results where the total amount is less then or equal to this value

contact_id
string GUID optional

Filter based on the contact that such event was performed against

Example:
8aea3eea-eb4d-b917-4b5a-7a2515638966
organisation_id
string GUID optional

Filters based on the organisation (identifier) that such event was performed on (applicable for PURCHASE)

Example:
8aea3eea-eb4d-b917-4b5a-7a2515638966
tap_code
string optional

Filters based on the organisation tap (code) that such event was performed on (applicable for PURCHASE)

Example:
0000257
cim
string optional

pending to be designed

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
event
Object

Details about the reward event

id
string GUID

The event identifier

Example:
5ee16b3d-090c-c178-d18f-c0035eeb1edb
type
string

The type of the event

Enumeration:
PURCHASE
REFERRAL
LOTTERY
THANK_YOU
CONTACT_REGISTRATION
PROFILE_COMPLETION
ACHIEVEMENT
AD_HOC_RETURN
REACH_TIER
SUBSCRIPTION_MATURITY
reference_number
string

The event reference number uniquely identifing the Customer Events

Example:
CE1234
state
string

The state of the event

Enumeration:
POSTED
CANCELLED
date
integer epoch

The date that the event was created

Example:
1614948921
total_amount
number

The amount that was posted as part of the event (applicable for PUCHASE and Ad Hoc Returns)

Example:
17.99
organisation
Object

Details about the organisation that such event was created by (if event = PURCHASE, defaults to the performed by organisation)

id
string GUID

The organisation identifier

Example:
5ee16b3d-090c-c178-d18f-c0035eeb1edb
name
string

The organisation name

Example:
CRM
type
string

The organisation type

Enumeration:
BUSINESS
MERCHANT
VENUE
classification
Object

Details about the event classification

id
string GUID

The classification identifier

Example:
c8d83493-3f50-40df-adb0-762ec5f41863
name
string

The classification name

Example:
Delivery Purchase
contact
Object

Details about the contact related to this event

id
string GUID

The contact identifier

Example:
9ec78c62-d56a-a43c-95e9-d6da4cc22d08
name
string

The contact full name

Example:
John Ray Doe
code
string

The contact code

Example:
123456789
cim
string

Unique Customer Identification Medium

Example:
1602754465
account
Object

Details about the contact’s account

id
string GUID

The account identifier

Example:
9ec78c62-d56a-a43c-95e9-d6da4cc22d08
name
string

The account name

Example:
John Ray Doe AR1234
number
string

The account number

Example:
AR1234
rewards
Object

Details about the reward related to this event

total_awards
number

The total amount awarded for this event

Example:
140.59
total_spends
number

The total amount spent by this event

Example:
12.21
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
GET https://sandbox.crm.com/backoffice/v1/reward_events HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "customer_events": {
                "id": "",
                "type": "PURCHASE",
                "reference_number": "",
                "life-cycle_state": "POSTED",
                "organisation": {
                    "id": "",
                    "name": ""
                },
                "contact": {
                    "id": "",
                    "name": "",
                    "code": ""
                },
                "referred_contact": {
                    "id": "",
                    "name": "",
                    "code": ""
                },
                "amount": 1,
                "date": 1
            },
            "award_spend": [
                {
                    "type": "SPEND",
                    "spend_method": "INSTANT_DISCOUNT",
                    "amount": "",
                    "reward_offer": {
                        "id": "",
                        "name": "Birthday Offer"
                    },
                    "reference_number": ""
                }
            ],
            "financial_transactions": [
                {
                    "id": "",
                    "reference_number": "",
                    "type": "INVOICE",
                    "life_cycle_state": "REJECTED",
                    "amount": ""
                }
            ],
            "wallet_fees": [
                {
                    "type": "DEBIT",
                    "id": "",
                    "amount": 1
                }
            ],
            "awards_without_purchase": {
                "id": "",
                "reference_number": "",
                "life_cycle_state": "POSTED",
                "reward_offer": "Welcome Offer EUR5",
                "type": "LOTTERY"
            }
        }
    ]
}
GET https://sandbox.crm.com/backoffice/v1/reward_events HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            
            "id": "mongoid",
            "entity_id":"dbid",
            "entity_type": "PURCHASE",
            "reference_number": "CE1234",
            "state": "POSTED",
            "submitted_date": 1614948921,
            "total_amount": 17.99,
            "currency":"EUR",
            "cancelled_by": {
                "id":"",
                "type":"PURCHASE_CANCELLED",
                "reference_number":""
            },
            "organisation": {
                "id": "",
                "name": "",
                "type":"MERCHANT"
            },
            "contact": {
                "id": "9ec78c62-d56a-a43c-95e9-d6da4cc22d08",
                "name": "John Ray Doe",
                "code": "123456789"
            },
            "account": {
                "id": "9ec78c62-d56a-a43c-95e9-d6da4cc22d08",
                "name": "John Ray Doe AR1234",
                "number": "AR1234"
            },
            "rewards": {
                "total_awards": 140.59,
                "total_spends": 12.21
            }
        }
    ]
}
List Reward Events Breakdown
GET /reward_events/{id}/details

Retrieves all transactions (e.g. award, spend, wallet, financial) related to a reward event

Path variables

id
string GUID required

The reward event (identifer) for which additional details will be retrieved

Example:
d46788e6-2c77-2948-2bb9-9521a0f54a8c

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
reward_transactions
Array

Details about award and spend transactions related to the event

Object
type
string

The type of the transaction

Enumeration:
AWARD
SPEND
code
string

The transaction (unique) code

Example:
123234342342432342324r43
amount
number

The amount that was awarded or spent

Example:
14.99
spend_method
string

Define how awards can be/were spent (for SPEND transactions only)

Enumeration:
AUTOMATIC_SPEND
INSTANT
ON_REQUEST
state
string

The transaction state

Enumeration:
POSTED
CANCELLED
EXPIRED

Only for Award Transactions

date
integer epoch

The date on which such transaction was posted

Example:
1614954223
reward_offer
Object

The reward offer that the promotion pass will consume.

id
string GUID

The reward offer identifier

Example:
c888dd7a-7476-538c-730a-9f924bd82d04
name
string

The reward offer name

Example:
Birthday Offer
financial_events
Array

Details about financial event related to the rewards event (can be the initiated transaction or the end result)

Object
type
string

The transaction type

Enumeration:
CREDIT_NOTE

Credit Note can initiate a reward event (purchase cancellation)

INVOICE

Invoice can initiate a reward event (purchase creation)

REFUND

Refund can be the result of a reward event (due to spend)

TOP_UP

Top-Up can initiate a reward event (achievement creation)

id
string GUID

The transaction identifier

Example:
7ff08bc0-c7e9-c9fe-f752-71cfb3ee0dc3
number
string

The transaction number

Example:
1234
reference_number
string

The transaction reference number

Example:
REF12343
life_cycle_state
string

The transaction life cycle state

Enumeration:
POSTED
REJECTED
amount
number

The transaction amount

Example:
112.24
date
integer epoch

The date on which such transaction was posted

Example:
1614954223
wallet_fees
Array

Details about the wallet fees related to the event

Object
type
string

Defines the reason for which the fee was applied on wallet

Enumeration:
CREDIT

On Credit Wallet Transactions

DEBIT

On Debit Wallet Transactions

id
string GUID

The wallet transaction identifier

Example:
4af933c7-2594-9c9c-d2d5-1ab4ff89fd59
amount
number

The fee amount

Example:
12.12
name
string

The fee rule name

Example:
1% on all wallet transactions
date
integer epoch

The date on which such fee was applied

Example:
1614954223
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/reward_events/d46788e6-2c77-2948-2bb9-9521a0f54a8c/details HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "reward_transactions": [
                {
                    "type": "AWARD",
                    "code": "123234342342432342324r43",
                    "amount": 14.99,
                    "currency":"EUR",
                    "spend_method": "INSTANT",
                    "state": "CANCELLED",
                    "date": 1614954223,
                    "reward_offer": {
                        "id": "7ff08bc0-c7e9-c9fe-f752-71cfb3ee0dc3",
                        "name": "Birthday Offer"
                    }
                }
            ],
            "financial_events": [
                {
                    "type": "CREDIT_NOTE",
                    "id": "7ff08bc0-c7e9-c9fe-f752-71cfb3ee0dc3",
                    "number": "1234",
                    "reference_number": "REF12343",
                    "life_cycle_state": "POSTED",
                    "amount": 112.24,
                    "currency":"EUR",
                    "date": 1614954223
                }
            ],
            "wallet_fees": [
                {
                    "type": "CREDIT",
                    "id": "4af933c7-2594-9c9c-d2d5-1ab4ff89fd59",
                    "amount": 12.12,
                    "currency":"EUR",
                    "name": "1% on all wallet transactions",
                    "date": 1614954223
                }
            ]
        }
    ]
}
Segments
POST /segments/{id}/export
POST /segments
PUT /segments/{id}
DELETE /segments/{id}
GET /segments
POST /segments/{id}/actions
GET /segments/{id}/contacts
POST /segments/{id}/conditions
GET /segments/{id}/conditions
Export Segment
POST /segments/{id}/export

Export the contacts of a segment to a .csv file and send it to the logged in user’s email

Path variables

id
string GUID required

The id of the Segment to export its contacts

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/segments/4AD9C84FA60F9FE407140E20F707726A/export HTTP/1.1 

HTTP/1.1 200 OK 
Create Segment
POST /segments

Create a new segment

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The segment’s name which i smandatory and has to be unique

Example:
Marketing customers
description
string nullable
Example:
A list of customers that own an accoun
refresh_frequency
string

How often the segment is automatically refreshed - provided in a cron expression pattern

Example:
0 0 12 * * ?
accessibility
Object

Defines which organisations can be access and use it

type
string required

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array nullable

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Unique items: YES
Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
Examples

Responses

200 200
Body
Object
id
string GUID

The segment identifier

Example:
ADD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/segments HTTP/1.1 

Content-Type: application/json

{
    "name": "Marketing customers",
    "description": "A list of customers that own an accoun",
    "refresh_frequency": "0 0 12 * * ?",
    "accessibility": {
        "type": "SPECIFIC_ORG",
        "organisations": [
            "CAD1E31269B76D7A65ACCE45B2E68DFD"
        ]
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ADD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Segment
PUT /segments/{id}

Updates the basic information of a segment

Path variables

id
string GUID required

The segment (identifier) that will be updated

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The segment name

Example:
All Contacts
description
string nullable

The segment’s description

Example:
List of contacts owning a non-terminated account
refresh_frequency
string nullable

How often the segment is automatically refreshed - provided in a cron expression pattern

Example:
0 0 12 * * ?
accessibility
Object nullable

Defines which organisations can be access and use it

type
string required

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array nullable

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Unique items: YES
Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 OK
Body
Object
id
string GUID

The segment identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/segments/c0d4712e-6688-4604-b3d6-d084e4d2dc05 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "All Contacts",
    "description": "List of contacts owning a non-terminated account",
    "refresh_frequency": "0 0 12 * * ?",
    "accessibility": {
        "type": "ACROSS_NETWORK",
        "organisations": [
            "CAD1E31269B76D7A65ACCE45B2E68DFD"
        ]
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05"
}
Delete Segment
DELETE /segments/{id}

Delete an existing segment

Path variables

id
string GUID required

The segment (identifier) that will be deleted

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/segments/c0d4712e-6688-4604-b3d6-d084e4d2dc05 HTTP/1.1 

HTTP/1.1 200 OK 
List Segments
GET /segments

Returns a list of Segments

Request parameters

from_date
integer epoch optional

The date from which the segment was created

Example:
1343423423
to_date
integer epoch optional

The date until which the segment was created

Example:
3234234234
search_value
string optional

Search for segments based on their name or description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
created_on
string optional

The date on which the segment was created. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two of the following options based on the required search:

Enumeration:
created_on[gt]

Returns results where the ‘created on’ field is greater than this value.

created_on[gte]

Return results where the ‘created on’ field is greater than or equal to this value.

created_on[lt]

Return results where the ‘created on’ field is less than or equal to this value.

created_on[lte]

Return results where the ‘created on’ field is less than or equal to this value.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The segment’s unique identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The segment’s name

Example:
Marketing customers
descripion
string

The segment’s description

Example:
List customers owning an account
size
integer

The segment’s size (total number of contacts)

Example:
95
imported_from
string

The Analytics tool from which the segment was imported

Enumeration:
MIXPANEL
Example:
MIXPANEL
resfresh_frequency
string

How often the segment is automatically refreshed - provided in a cron expression

Example:
0 0 12 * * ?
accessibility
Object

Defines how the segment can be accessed from business network

type
string

Defines which organisations can access and use it

Enumeration:
BUSINESS
ACROSS_NETWORK
SPECIFIC_ORG
organisations
Array

The organisations (Merchants, Service Providers) that can access and use it (applicable only if type = SPECIFIC)

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
CRM
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/segments HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Marketing customers",
            "descripion": "List customers owning an account",
            "size": 95,
            "imported_from": "MIXPANEL",
            "resfresh_frequency": "0 0 12 * * ?",
            "accessibility": {
                "type": "ACROSS_NETWORK",
                "organisations": [
                    {
                        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                        "name": "CRM"
                    }
                ]
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Perform Segment Actions
POST /segments/{id}/actions

Perform an action on an existing segment.

Path variables

id
string GUID required

The segment (identifier) on which an action is performed

Example:
3ebf9ee1-6a38-85db-f7f5-605becaf2022

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The action to be performed on the segment

Enumeration:
REFRESH
Default:
REFRESH

Responses

200 OK
Body
Object
id
string GUID

The segment identifier

Example:
ADD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/segments/{id}/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "REFRESH"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ADD1E31269B76D7A65ACCE45B2E68DFD"
}
Get Contacts in Segment
GET /segments/{id}/contacts

Returns a list of contacts which are included in an existing segment.

Path variables

id
string GUID required

The segment (identifier) of which contact will be retrieved

Example:
3ebf9ee1-6a38-85db-f7f5-605becaf2022

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for contacts based on their code, name, phone or email address

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The contact’s unique identifier

Example:
5e2fc32d-efb5-8c5a-b4c5-7e3861db8ddd
name
string

The contact’s name (full name for Persons, company name for Companies)

Example:
John Smith
code
string

The contact’s code

Example:
0049304938571623
phone_number
string

The contact’s phone number

Example:
+306954000112
email_address
string

The contact’s email address

Example:
bill@gmail.com
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/segments/{id}/contacts HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "John Smith",
            "code": "0049304938571623",
            "phone_number": "+306954000112",
            "email_address": "bill@gmail.com"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Add Segment Conditions
POST /segments/{id}/conditions

Adds a set of conditions in a segment

Path variables

id
string GUID required

The segment (identifier) on which conditions will be added

Example:
Quick GUID 7f3a6d04-6a91-2100-9058-eaa9f4972169

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
groups
Array

A segment includes multiple groups of conditions.

Object
name
string required

The name of the conditions group. If not specified, then the group is named after a letter of the Latin alphabet starting from A, then B etc.

Example:
A
type
string required

Each group includes conditions that refer to either an Event that was performed or Contact information

Enumeration:
EVENT
CONTACT
event_name
string required nullable

The name of the event that a contact performed or not. Applicable and required only for conditions of type Event. If not specified, then contacts that performed any event are eligible to be included in the segment

Enumeration:
PURCHASE
PURCHASE_CANCELLED
AWARD
SPEND
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
ORDER
REFERRAL
REFERRAL_CANCELLED
TOP_UP
TRANSFER
inclusion
string required

Defines the operator that will be used accoridng to the condition’s type. When the condition refers to an Event, then contact are included in the segment if they did or did not perform that Event. When the condition refers to Contact information, then contacts are included in the segment if they have or do not have the specified contact related information.

Enumeration:
DID

Applicable for Events only

DID_NOT

Applicable for Events only

HAVE

Applicable for Contacts only

HAVE_NOT

Applicable for Contacts only

frequency
Object

The frequency of an event, i.e hw many times an Event occured withn a period of time. Applicable and required for Event conditions.

operator
string required

The frequency’s operator

Enumeration:
AT_LEAST
BETWEEN
MORE_THAN
LESS_THAN
EQUAL
Default:
AT_LEAST
min_times
integer required

The minimum number of times the Event occured.

Example:
1
max_times
integer nullable

The maximum number of times the Event occured. Required only when the operator is set to BETWEEN

Example:
5
period
Object nullable

The period of time during which the Event(s) occured

operator
string required

The operator that shows he period of time during which Events must fall within in order for contacts to be included in the segment. Operators Between, On, Since require date(s) filters, whereas the rest of the operators need an integrer value(s)

Enumeration:
BETWEEN
SINCE
ON
LAST_DAYS
LAST_MONTHS
LAST_HOURS
LAST_WEEKS
from
string required

The starting period of time. For dates, this should be an epoch value

Example:
1
to
string nullable

The ending period. Required only for Between operator. For dates, this should be an epoch value

Example:
3
type
string required

The from/to filters date type depending on the selected operator.

Enumeration:
STRING
NUMBER
DATE
INTEGER
properties_operator
string required

Multiple properties can be added to apply additional filtering on the conditions. So if more than one properties are specified, an operator is required that defines the logic between properties. This operator can only be ALL (all properties must be met) or ANY (at least one must be met) to incldue the contact in the segment.

Enumeration:
ALL
ANY
Default:
ALL
properties
Array

List of event properties/attibutes that can be used as additional filtering conditions.

Object
property
string required

The name of the property which depends on the selected event. Each event has its own set of properties.

Example:
purchase.amount
operator
string required

The property’s condition operator

Enumeration:
IS
IS_NOT
ON
BEFORE
AFTER
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
IS_EMPTY
IS_NOT_EMPTY
STARTS_WITH
DOES_NOT_START_WITH
ENDS_WITH
DOES_NOT_END_WITH
LIKE
NOT_LIKE
EQUAL
NOT_EQUAL
LESS_THAN_OR_EQUAL
MORE_THAN_OR_EQUAL
min_value
string required

The property’s value or in the case of range operator like Between, the starting value.

Example:
5.00
max_value
string nullable

The maximum value for the property, required when using “range” operators like Between.

Example:
10
value_list
Array of string nullable

List of String values required when the operator implies multiple values comparison like Contains,Does not contain.

type
string required

The property’s data type

Enumeration:
STRING
NUMBER
INTEGER
DATE
list_name
string nullable

Applicable only if the property is a list and represents the list name

Example:
products
logical_expression
string required

The logical expression between the Groups. Required if more than one groups are specified

Example:
(A OR B) AND C

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

DO NOT DELETE/REGENERATE!!!
Example 2

Customers who did 3-5 purchases of more than 5 euros in Freddo espresso/Espresso in the last 3 weeks AND these customers are either Persons with a birthday set but not employees or vips OR companies in Petrol/Gas station industries

POST https://devapi.crm.com/backoffice/v1/segments/{id}/conditions HTTP/1.1 

Content-Type: application/json

{
    "groups": [
        {
            "name": "A",
            "type": "EVENT",
            "event_name": "PURCHASE",
            "inclusion": "DID",
            "frequency": {
                "operator": "BETWEEN",
                "min_times": 1,
                "max_times": 5,
                "period": {
                    "operator": "LAST_WEEKS",
                    "from": "3",
                    "to": ""
                }
            },
            "properties_operator":"ALL",
            "properties": [
                {
                    "property": "purchase.amount",
                    "operator": "MORE_THAN",
                    "min_value": "5.00",
                    "max_value": "",
                    "value_list": [
                        ""
                    ]
                },
                {
                    "property": "purchase.products.name",
                    "operator": "CONTAINS",
                    "min_value": "",
                    "max_value": "",
                    "value_list": [
                        "Freddo Espresso","Espresso"
                    ]
                }
            ]
        },
        {
            "name": "B",
                                "type": "CONTACT",
            "event_name": "",
            "inclusion": "HAVE",
            "properties_operator":"AT_LEAST",
            "properties": [
                {
                    "property": "type",
                    "operator": "EQUALS",
                    "min_value": "PERSON",
                    "max_value": "",
                    "value_list": [
                        ""
                    ]
                },
                {
                    "property": "birthday.month",
                    "operator": "NOT_EMPTY",
                    "min_value": "",
                    "max_value": "",
                    "value_list": [
                        ""
                    ]
                },
                {
                    "property": "category.name",
                    "operator": "EQUAL",
                    "min_value": "",
                    "max_value": "",
                    "value_list": [
                        "VIP","Employees"
                    ]
                }
            ]

        },
        {
            "name": "C",
            "type": "COTNACT",
            "event_name": "",
            "inclusion": "HAVE",
            "properties_operator":"ALL",
            "properties": [
                {
                    "property": "type",
                    "operator": "EQUALS",
                    "min_value": "COMPANY",
                    "max_value": "",
                    "value_list": [
                        ""
                    ]
                },
                {
                    "property": "insdustry.name",
                    "operator": "CONTAINS",
                    "min_value": "",
                    "max_value": "",
                    "value_list": [
                        "Petrol","Gas Stations"
                    ]
                }
            ]
        }
    ]
}
POST https://sandbox.crm.com/backoffice/v1/segments/{id}/conditions HTTP/1.1 

Content-Type: application/json

{
    "groups": [
        {
            "name": "A",
            "type": "EVENT",
            "event_name": "PURCHASE",
            "inclusion": "DID",
            "frequency": {
                "operator": "AT_LEAST",
                "min_times": 1,
                "max_times": 5,
                "period": {
                    "operator": "LAST_MONTHS",
                    "from": "1",
                    "to": "3",
                    "type": "INTEGER"
                }
            },
            "properties_operator": "ALL",
            "properties": [
                {
                    "property": "purchase.amount",
                    "operator": "IS",
                    "min_value": "5.00",
                    "max_value": "10",
                    "value_list": [
                        ""
                    ],
                    "type": "STRING",
                    "list_name": "products"
                }
            ]
        }
    ],
    "logical_expression": "(A OR B) AND C"
}

HTTP/1.1 200 OK 
Get Segment Conditions
GET /segments/{id}/conditions

Returns a segment’s set of conditions

Path variables

id
string GUID required

The segment (identifier) of which conditions will be retrieved

Example:
ad7a97fe-104a-8eb1-a49b-1f4b766e53a8

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
groups
Array

A segment includes multiple groups of conditions.

Object
name
string

The name of the conditions group. If not specified, then the group is named after a letter of the Latin alphabet starting from A, then B etc.

Example:
A
type
string

Each group includes conditions that refer to either an Event that was performed or Contact information

Enumeration:
EVENT
CONTACT
event_name
string

The name of the event that a contact performed or not. Applicable and required only for conditions of type Event. If not specified, then contacts that performed any event are eligible to be included in the segment

Enumeration:
PURCHASE
PURCHASE_CANCELLED
AWARD
SPEND
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
ORDER
REFERRAL
REFERRAL_CANCELLED
TOP_UP
TRANSFER
inclusion
string

Defines the operator that will be used accoridng to the condition’s type. When the condition refers to an Event, then contact are included in the segment if they did or did not perform that Event. When the condition refers to Contact information, then contacts are included in the segment if they have or do not have the specified contact related information.

Enumeration:
DID

Applicable for Events only

DID_NOT

Applicable for Events only

HAVE

Applicable for Contacts only

HAVE_NOT

Applicable for Contacts only

frequency
Object

The frequency of an event, i.e hw many times an Event occured withn a period of time. Applicable and required for Event conditions.

operator
string

The frequency’s operator

Enumeration:
AT_LEAST
BETWEEN
MORE_THAN
LESS_THAN
EQUAL
Default:
AT_LEAST
min_times
integer

The minimum number of times the Event occured.

Example:
1
max_times
integer

The maximum number of times the Event occured. Required only when the operator is set to BETWEEN

Example:
5
period
Object

The period of time during which the Event(s) occured

operator
string

The operator that shows he period of time during which Events must fall within in order for contacts to be included in the segment. Operators Between, On, Since require date(s) filters, whereas the rest of the operators need an integrer value(s)

Enumeration:
BETWEEN
SINCE
ON
LAST_DAYS
LAST_MONTHS
LAST_HOURS
LAST_WEEKS
from
string

The starting period of time. For dates, this should be an epoch value

Example:
3
to
string

The ending period. Required only for Between operator. For dates, this should be an epoch value

Example:
5
type
string

The operator that shows he period of time during which Events must fall within in order for contacts to be included in the segment. Operators Between, On, Since require date(s) filters, whereas the rest of the operators need an integrer value(s)

Enumeration:
BETWEEN
SINCE
ON
LAST_DAYS
LAST_MONTHS
LAST_HOURS
LAST_WEEKS
properties_operator
string

Multiple properties can be added to apply additional filtering on the conditions. So if more than one properties are specified, an operator is required that defines the logic between properties. This operator can only be ALL (all properties must be met) or ANY (at least one must be met) to incldue the contact in the segment.

Enumeration:
ALL
ANY
Default:
ALL
Example:
ALL
properties
Array

List of event properties/attibutes that can be used as additional filtering conditions.

Object
property
string required

The name of the property which depends on the selected event. Each event has its own set of properties.

Example:
purchase.amount
operator
string

The property’s condition operator

Enumeration:
IS
IS_NOT
ON
BEFORE
AFTER
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
IS_EMPTY
IS_NOT_EMPTY
STARTS_WITH
DOES_NOT_START_WITH
ENDS_WITH
DOES_NOT_END_WITH
LIKE
NOT_LIKE
EQUAL
NOT_EQUAL
LESS_THAN_OR_EQUAL
MORE_THAN_OR_EQUAL
min_value
string required

The property’s value or in the case of range operator like Between, the starting value.

Example:
5.00
max_value
string

The maximum value for the property, required when using “range” operators like Between.

Example:
10
value_list
Array of string

List of String values required when the operator implies multiple values comparison like Contains,Does not contain.

type
string

The property’s data type

Enumeration:
STRING
NUMBER
INTEGER
DATE
list_name
string

Applicable only if the property is a list and represents the list name

Example:
products
logical_expression
string required

The logical expression between the Groups. Required if more than one groups are specified

Example:
(A OR B) AND C
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/segments/{id}/conditions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "groups": [ 
        {
            "name": "A",
            "type": "EVENT",
            "event_name": "PURCHASE",
            "inclusion": "DID_NOT",
            "frequency": {
                "operator": "AT_LEAST",
                "min_times": 1,
                "max_times": 5,
                "period": {
                    "operator": "LAST_MONTHS",
                    "from": "3",
                    "to": "5",
                    "type": "INTEGER"
                }
            },
            "properties_operator": "ALL",
            "properties": [
                {
                    "property": "purchase.amount",
                    "operator": "LIKE",
                    "min_value": "5.00",
                    "max_value": "10",
                    "value_list": [
                        ""
                    ],
                    "type": "STRING",
                    "list_name": "products"
                }
            ]
        }
    ],
    "logical_expression": "(A OR B) AND C"
}
Service Requests
POST /service_requests
PUT /service_requests/{id}
DELETE /service_requests/{id}
GET /service_requests
GET /service_requests/{id}
POST /service_requests/{id}/statuses
GET /service_requests/{id}/statuses
Create Service Request
POST /service_requests

Create a new service request

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string GUID required

Contacts unique identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
queue_id
string GUID required

The queue unique id.

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
description
string

A description of the service request.

Example:
The client has an an issue with their billing.
applies_to
Array

Further details of the service request and what it applies

Object
entity_id
string GUID

The unique GUID of the service

Example:
ABCDAKJHKFJH862476
entity_type
string

The type of object that it applies to

Enumeration:
SUBSCRIPTION_SERVICES
categories
Array of string GUID

The categories applicable to this service request.

Unique items: YES
Example:
[
    "djkjfhdskjhskdjh"
]
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
assign_to
Object nullable
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
owner_id
string GUID nullable

Defines the owner (user) that is reponsible for this service request

Example:
1ca16b72-9e38-bd02-3dbe-6419b6f904cf
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
address
Object

Address information for the service request

id
string nullable

The contact’s address id associated to the service request (either ‘id’ or ‘other’ can be specified)

Example:
61c943c8-dfeb-4c09-a25c-b054f48bf244
other
Object nullable
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The GUID for the new service request

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "queue_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "description": "The client has an an issue with their billing.",
    "applies_to": [
        {
            "entity_id": "ABCDAKJHKFJH862476",
            "entity_type": "SUBSCRIPTION_SERVICES"
        }
    ],
    "categories": [
        ""
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "assign_to": {
        "user_id": "1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf",
        "team_id": "a43f08ca-998b-afbc-6ed4-c9dc2d136935"
    },
    "owner_id": "1ca16b72-9e38-bd02-3dbe-6419b6f904cf",
    "urgency": "LOW",
    "impact": "MEDIUM",
    "address": {
        "id": "61c943c8-dfeb-4c09-a25c-b054f48bf244",
        "other": {
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2015",
            "country": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Service Request
PUT /service_requests/{id}

Update an existing service request

Path variables

id
string GUID required

The GUID of the service request to be updated

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
description
string

A description of the service request.

Example:
The client has an an issue with their billing.
approx_close_date
integer epoch

The calculated aproximate close date&time of the service request based off of the queue type and priority.

Example:
78676786
alert_date
integer epoch

The calculated alert time based off the queue type and priority set for this service request.

Example:
87623764
priority_matrix
Object
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
categories
Array of string GUID

The categories associated to service request

Unique items: YES
applies_to
Array

Further details of the service request and what it applies

Object
entity_type
string

The type of object that it applies to

Enumeration:
SUBSCRIPTION_SERVICES
entity_id
string GUID

The newly added service (identifier)

Example:
ce4a1856-eaf0-be8a-9a85-7169f9859175
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
assign_to
Object nullable
user_id
string GUID

The user identifier

Example:
1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf
team_id
string GUID

The team identifier

Example:
a43f08ca-998b-afbc-6ed4-c9dc2d136935
owner_id
string nullable

Defines the owner (user) that is reponsible for this service request

address
Object

Address information for the service request

id
string nullable

The contact’s address id associated to the service request (either ‘id’ or ‘other’ can be specified)

Example:
61c943c8-dfeb-4c09-a25c-b054f48bf244
other
Object nullable
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The GUID for the new service request

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/service_requests/HPA1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "description": "The client has an an issue with their billing.",
    "approx_close_date": 78676786,
    "alert_date": 87623764,
    "priority_matrix": {
        "urgency": "LOW",
        "impact": "HIGH"
    },
    "categories": [
        ""
    ],
    "applies_to": [
        {
            "entity_type": "SUBSCRIPTION_SERVICES",
            "entity_id": "ce4a1856-eaf0-be8a-9a85-7169f9859175"
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "assign_to": {
        "user_id": "1edef819-0a1d-4d41-9d2a-d4bbc2ddbedf",
        "team_id": "a43f08ca-998b-afbc-6ed4-c9dc2d136935"
    },
    "owner_id": "",
    "address": {
        "id": "61c943c8-dfeb-4c09-a25c-b054f48bf244",
        "other": {
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2015",
            "country": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
        }
    }
}
Delete Service Request
DELETE /service_requests/{id}

Delete a single service request.

Path variables

id
string GUID required

The GUID of the service request to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/service_requests/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 
List Service Requests
GET /service_requests

Retrieve all service requests

Request parameters

page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
search_value
string optional

Search for a service request using Contact person’s name, Owner, Description, ticket number,status, date_created, date_closed

Example:
SR0001ABC,NAME,OWNER,DESCRIPTION,TICKET NUMBER,QUEUE, STATUS, DATE_CREATED, DATE_CLOSED
queue_id
string optional

The queue GUID (to view service request)

contact_id
string optional

The unique contact id

from_date
integer optional

The date from which the service request was created

to_date
integer optional

The date until which the service request was created

resolved
boolean optional

Whether the SR is resolved. Default is unresolved

created_on
string optional

Filter based on the created date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. created_on[gte]=1618395497&created_on[lt]=1618395497).

Enumeration:
created_on[gt]

Returns results where the created date is greater than this value

created_on[gte]

Returns results where the created date is greater than or equal to this value

created_on[lt]

Returns results where the created date is less than this value

created_on[lte]

Returns results where the created date is less then or equal to this value

priority
string optional

Filter based on priority

Enumeration:
URGENT
HIGH
MEDIUM
LOW
status_ids
array of string optional

Array of queue statuses GUID’s.

Collection format: csv
tag_ids
array of string optional

List of tag ids to filter by

Collection format: csv
closure_reason_ids
array of string optional

List of closure reasons to filter records by

Collection format: csv
approx_close_date
string optional

The approximate closure date of SR. Date range. ie. between today and next week Monday.The value can be a string with a date in epoch format. Each option must also include an operator. Eg: &expected_close_date.[gte]=1609459200&expected_close_date.[lt]=1609459200. Use up to two of the following options based on the required search:

Enumeration:
approx_close_date[gt]

Returns results where the ‘approx_close_date’ field is greater than this value.

approx_close_date[gte]

Return results where the ‘approx_close_date’ field is greater than or equal to this value.

approx_close_date[lt]

Return results where the ‘approx_close_date’ field is less than or equal to this value.

approx_close_date[lte]

Return results where the ‘approx_close_date’ field is less than or equal to this value.

alert_date
string optional

The alert dates of SR’s. Date range. ie. between today and next week Monday.The value can be a string with a date in epoch format. Each option must also include an operator. Eg: &expected_close_date.[gte]=1609459200&expected_close_date.[lt]=1609459200. Use up to two of the following options based on the required search:

Enumeration:
alert_date[gt]

Returns results where the ‘alert_date’ field is greater than this value.

alert_date[gte]

Return results where the ‘alert_date’ field is greater than or equal to this value.

alert_date[lt]

Return results where the ‘alert_date’ field is less than or equal to this value.

alert_date[lte]

Return results where the ‘alert_date’ field is less than or equal to this value.

include_custom_fields
boolean optional

Defines whether custom fields should be retrieved or not (via List/Get APIs)

Default:
false
Example:
true
custom_fields
string optional

Filters based on custom fields (key/value set should be semicolon separated)

Example:
key;value
category_ids
array of string optional
Collection format: csv
assign_to_user_id
string GUID optional

Filters based on specific assign to user

Example:
c45903ff-4a00-49bd-93b4-6b2f0373ce20
assign_to_team_id
string GUID optional

Filters based on specific assign to team

Example:
5beb415c-3246-1a10-f806-3f975e4898dc
include_approvals
boolean optional

Defines whether approval requests information should be retrieved or not

Example:
true
approval_state
string optional

Filter based on approval request state

Enumeration:
PENDING
APPROVED
REJECTED

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The service request unique identifier

Example:
LEM1E31269B76D7A65ACCE45B2E68DFD
number
string

The unique ticket number relating to the request

Example:
SR0001ABC
description
string

A brief description of the service request

Example:
service request was submitted based off of billing issues
creation_date
integer epoch

The creation date of the service request

Example:
98765342
alert_date
integer epoch

The calculated alert time based off the queue type and priority set for this service request.

approx_close_date
integer epoch

The approx close date of SR.

priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW
resolved
boolean

Whether the SR has been resolved.

queue
Object

service request queue information

id
string GUId

The service request queue id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The service request queue name

Example:
Billing Issues
queue_status
Object

Current queue status information

id
string GUID

The current service request queue status unique id

Example:
KVX1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the current service request queue status

Example:
Proposal submitted
color
string

The color code associated to the status

Example:
#FDS7GH
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
categories
Array

The categories associated to the service request

Object
id
string GUID

The id of the categories

Example:
HSGJHGFJSF86876JUGDSJHG
name
string

The name of the caetgory

Example:
Maintenance issues
closure_reason
Object

The closure reasons related to the service request

id
string

The id of the closure reason for this service request

name
string

The name to be displayed

Example:
Reffered to Installer
tags
Array
Object
id
string

Tag ID

Example:
JHGJHGJHGHJi87987
name
string

Name of Tag

Example:
Maintenance
colour
string

The colour of the tag - for list view only.

Example:
FR547F
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
approvals
Object

Details about the latest requested approval(s)

state
string

The approval request state

Enumeration:
PENDING
APPROVED
REJECTED
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "LEM1E31269B76D7A65ACCE45B2E68DFD",
            "number": "SR0001ABC",
            "description": "service request was submitted based off of billing issues",
            "creation_date": 98765342,
            "alert_date": 1,
            "approx_close_date": 1,
            "priority": "LOW",
            "resolved": true,
            "queue": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Billing Issues"
            },
            "queue_status": {
                "id": "KVX1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Proposal submitted",
                "color": "#FDS7GH"
            },
            "contact": {
                "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
                "name": "John Johnson",
                "code": "C123"
            },
            "categories": [
                {
                    "id": "HSGJHGFJSF86876JUGDSJHG",
                    "name": "Maintenance issues"
                }
            ],
            "closure_reason": {
                "id": "",
                "name": "Reffered to Installer"
            },
            "tags": [
                {
                    "id": "JHGJHGJHGHJi87987",
                    "name": "Maintenance",
                    "colour": "FR547F"
                }
            ],
            "custom_fields": [
                {
                    "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a",
                    "key": "back_office",
                    "label": "Back Office",
                    "description": "The account's back office code",
                    "tooltip": "",
                    "visible": true,
                    "field": "MULTIPLE_LINES",
                    "entity": "ORDERS"
                }
            ],
            "assign_to": {
                "user": {
                    "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
                    "name": "John Doe",
                    "username": "j_doe@crm.com"
                },
                "team": {
                    "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
                    "name": "Support"
                }
            },
            "owner": {
                "id": "",
                "username": "",
                "name": ""
            },
            "address": {
                "address_line_1": "Elia Papakyriakou",
                "address_line_2": "7 Tower Stars",
                "state_province_county": "Egkomi",
                "town_city": "Nicosia",
                "postal_code": "2015",
                "country": "CYP",
                "lat": 35.157115,
                "lon": 33.313719,
                "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Service Request
GET /service_requests/{id}

Retrieve the information for a specific service request.

Path variables

id
string required

The service request identifier (GUID) of the service request to be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string
Example:
SR0001ABC
description
string
Example:
The customer can not link their card
response
string

If the service request has been ‘Closed’ the response should be returned.

Example:
Installation issue.
resolved
boolean

Whether SR has been resolved.

Example:
true
alert_date
integer epoch

The calculated alert time based off the queue type and priority set for this service request.

approx_close_date
integer epoch

The calculated aproximate close date&time of the service request based off of the queue type and priority.

queue
Object
id
string
Example:
LMP1E31269B76D7A65ACCE45B2E68DFD
name
string
Example:
Billing issues
priority_matrix
Object
priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
contact
Object

Details about the related contact

id
string GUID

The contact identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact full name

Example:
John Johnson
code
string

The contact unique code

Example:
C123
queue_status
Object
id
string

The GUID of the status

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The name of the status

Example:
Response submitted
priority
integer

The priority of this status in the sequence

Example:
5
colour
string

The colour relating to this status

Example:
#FA89CB
closure_reason
Object

The closure reason

id
string

The id relating to the closure reason

Example:
KJGKJGJG76786JHFJHF
name
string

The name realting to the closure reason.

Example:
Referred to installer
description
string

The closure reason description

invoice
Object

The invoice that was raised against the service request when the service request was CLOSED.

id
string
Example:
JGDKJHKDJAHKSHi6876
number
string
Example:
INV87386IUGY
applies_to
Array

This is an array of the objects to which this request applies to.

Object
entity_id
string

The unique GUID of the subscription service.

Example:
PLE1E31269B76D7A65ACCE45B2E68DFD
entity_type
string

The type of object that it applies to

Enumeration:
SUBSCRIPTION_SERVICES
entity_value
string

The name/number of the object.If the entity_type is SUBSCRIPTION_SERVICES then the entity_value should be the entity’s name.

Example:
Streaming service, P007NDR
life_cycle_state
string
Example:
EFFECTIVE
categories
Array
Object
id
string GUID

The id of the category

Example:
JKFGHJHFGSJHGSFJHGF
name
string

The name of the category.

Example:
Maintenance
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
assign_to
Object
user
Object

Details about the user that the record is assigned to

id
string GUID

The user identifier

Example:
47ac694d-6281-b873-bf46-3fd8da334a3a
name
string

The user name

Example:
John Doe
username
string

The username of the user

Example:
j_doe@crm.com
team
Object

Details about the team that the record is assigned to

id
string GUID

The team identifier

Example:
bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe
name
string

The team name

Example:
Support
address
Object
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "number": "SR0001ABC",
    "description": "The customer can not link their card",
    "response": "Installation issue.",
    "resolved": true,
    "alert_date": 1,
    "approx_close_date": 1,
    "queue": {
        "id": "LMP1E31269B76D7A65ACCE45B2E68DFD",
        "name": "Billing issues"
    },
    "priority_matrix": {
        "priority": "HIGH",
        "urgency": "MEDIUM",
        "impact": "LOW"
    },
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "queue_status": {
        "id": "6A24D2B5E44F44B28451FE021FCAD51E",
        "name": "Response submitted",
        "priority": 5,
        "colour": "#FA89CB"
    },
    "closure_reason": {
        "id": "KJGKJGJG76786JHFJHF",
        "name": "Referred to installer",
        "description": ""
    },
    "invoice": {
        "id": "JGDKJHKDJAHKSHi6876",
        "number": "INV87386IUGY"
    },
    "applies_to": [
        {
            "entity_id": "PLE1E31269B76D7A65ACCE45B2E68DFD",
            "entity_type": "SUBSCRIPTION_SERVICES",
            "entity_value": "Streaming service, P007NDR",
            "life_cycle_state": "EFFECTIVE"
        }
    ],
    "categories": [
        {
            "id": "JKFGHJHFGSJHGSFJHGF",
            "name": "Maintenance"
        }
    ],
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ],
    "assign_to": {
        "user": {
            "id": "47ac694d-6281-b873-bf46-3fd8da334a3a",
            "name": "John Doe",
            "username": "j_doe@crm.com"
        },
        "team": {
            "id": "bf1370a1-73ad-0bbf-6fef-f2ce1938d4fe",
            "name": "Support"
        }
    },
    "owner": {
        "id": "",
        "name": "",
        "username": ""
    },
    "address": {
        "address_line_1": "Elia Papakyriakou",
        "address_line_2": "7 Tower Stars",
        "state_province_county": "Egkomi",
        "town_city": "Nicosia",
        "postal_code": "2015",
        "country": "CYP",
        "lat": 35.157115,
        "lon": 33.313719,
        "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
    }
}
Update Service Request Queue Status
POST /service_requests/{id}/statuses

Change the queue status of a service request (e.g. progress a service request).

Path variables

id
string required

The GUID of the service request whose queue status will be changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
queue_status_id
string

The new service request queue status ID

Example:
CEEE83D6E0804A30966F684B0269AD91
date_achieved
integer epoch required

Defaults to current date & time

Example:
1583846865
regression_reason
string

The reason that the service request needs to be moved back to a previous status.

Example:
The issue has changed and the ticket needs to be moved back to awaiting customer.
response
string

The response to the Service Request. This is NOT required when status is ‘Closed’.This is optional due to the closure response selection.

Example:
This issue is closed and mitigated. Faulty installation.
resolved
boolean

The status of the request upon closing. This is required when status is ‘Closed’.

account_id
string

The account id relating to the charges associated with the service request. This account will be invoiced for the charges when closing the service request.

Example:
HDFSFGFDSGS
closure_reason_id
string

When the status is ‘Closed’ and the resolved = False. This is required.

Example:
JKJHDKJHAKJHASH
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the service request whose queue status was changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
approval_requests
Array

Determines whether approval reuqests are applied or not, if not null an approval is requested

Object
id
string GUID

The apporval request identifier

Example:
3a4aad81-e5c2-72b7-3a86-903239d08767
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/HPA1E31269B76D7A65ACCE45B2E68DFD/statuses HTTP/1.1 

Content-Type: application/json

{
    "queue_status_id": "CEEE83D6E0804A30966F684B0269AD91",
    "date_achieved": 1583846865,
    "regression_reason": "The issue has changed and the ticket needs to be moved back to awaiting customer.",
    "response": "This issue is closed and mitigated. Faulty installation.",
    "resolved": true,
    "account_id": "HDFSFGFDSGS",
    "closure_reason_id": "JKJHDKJHAKJHASH"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "HPA1E31269B76D7A65ACCE45B2E68DFD",
    "approval_requests": [
        {
            "id": "3a4aad81-e5c2-72b7-3a86-903239d08767"
        }
    ]
}
List Service Request Queue Statuses
GET /service_requests/{id}/statuses

Retrieve all the queue statuses a service request has progressed through.

Path variables

id
string required

The GUID of the service request whose queue status will be retrieved

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The id of the service request.

Example:
558269B76D7A65ACCE45B2E68DFD
date_achieved
integer

The date of that status acheived.

Example:
98765342
regression_reason
string

The response to why the request has been regressed

Example:
The issue has changed and will there have to move back to awaiting response.
modified_date
integer epoch

Date SR status modified (relevant to service request history)

Example:
98765342
queue_status
Object
id
string

id of the queue status

Example:
KUHSKHSKUH&5765675
name
string

name of the queue status

Example:
Waiting for customer
colour
string

Colour relating to the queue status

Example:
87GFD8
priority
integer

The order of prioirty of the queue status.

Example:
1
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/HPA1E31269B76D7A65ACCE45B2E68DFD/statuses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "558269B76D7A65ACCE45B2E68DFD",
            "date_achieved": 98765342,
            "regression_reason": "The issue has changed and will there have to move back to awaiting response.",
            "modified_date": 98765342,
            "queue_status": {
                "id": "KUHSKHSKUH&5765675",
                "name": "Waiting for customer",
                "colour": "87GFD8",
                "priority": 1
            }
        }
    ]
}
Attachments
POST /service_requests/{id}/files
DELETE /service_requests/{id}/files/{file_id}
GET /service_requests/{id}/files
Add Service Request Attachment File
POST /service_requests/{id}/files

Connect an uploaded file to an existing service request

Path variables

id
string GUID required

The service request (identifier) that file will be attached

Example:
66451204-4404-894c-4dc6-486c540ece40

Notes

FILE UPLOAD FLOW

Integrating file upload for Service Requests should be based on the following APIs

  1. Upload File Signature
  2. Connect a file to a Service Request

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
file_id
string GUID required nullable

The file (identifier) to be attached

Example:
30526723-24a3-e4e3-1a75-b26b1b41f05c
url
string required nullable

URL of the file to be attached

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
description
string nullable

The file description

Example:
Screenshot sent by customer

Responses

200 OK
Body
Object
id
string GUID

The service request identifier

Example:
66451204-4404-894c-4dc6-486c540ece40
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

Content-Type: application/json

{
    "file_id": "30526723-24a3-e4e3-1a75-b26b1b41f05c",
    "url": "https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug",
    "description": "Screenshot sent by customer"
}
Delete Service Request Attachment File
DELETE /service_requests/{id}/files/{file_id}

Delete a specific service request attachment file

Path variables

id
string GUID required

The service request (identifier) that file will be deleted

Example:
66451204-4404-894c-4dc6-486c540ece40
file_id
string GUID required

The attachment file (identifier) that will be deleted

Example:
04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/service_requests/66451204-4404-894c-4dc6-486c540ece40/files/04c0bebd-8bb0-0b3e-e1a6-716a0fd200b1 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Service Requests Attachment Files
GET /service_requests/{id}/files

Retrieve all attachment files for a specific service request

Path variables

id
string GUID required

The service request (identifier) that files will be retrieved

Example:
66451204-4404-894c-4dc6-486c540ece40

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The attachment identifier

Example:
3ae9d64a-8a3b-f1e1-eed6-05b307f926fb
mime
string

The mime type of the uploaded file

Enumeration:
csv
doc
docx
xls
xlsx
pdf
log
txt
png
jpg
jpeg
svg
description
string

The attachement description

Example:
Screenshot sent by customer
file
Object

The attachement file details

id
string GUID

The file identifier

Example:
0317868f-28f8-9f56-d248-5a78718b38cc
url
string

The file URL endpoint

Example:
https://crmcom.sharepoint.com/:x:/s/servicerequests/EZx2qopbvfN3uj1o3dOqbPm52Ct6bg?rtime=w0ic-hfG2Ug
name
string

The file name

Example:
img.png
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/66451204-4404-894c-4dc6-486c540ece40/files HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3ae9d64a-8a3b-f1e1-eed6-05b307f926fb",
            "mime": "png",
            "description": "this is a brief description of this image",
            "file": {
                "id": "0317868f-28f8-9f56-d248-5a78718b38cc",
                "name": "img.png"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Charges

Ability to add products as charges on a service request.

POST /service_requests/{id}/charges
PUT /service_requests/{id}/charges
GET /service_requests/{id}/charges
Create Charges for Service Request
POST /service_requests/{id}/charges

Creates charges on service requests includes the price, as well as taxes to be applied.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string

The account to which the charges will be associated with.

discount
Object
amount
number
type
string
Enumeration:
AMOUNT
PERCENTAGE
line_items
Array required
Min items: 1
Object
product_id
string GUID required

The unique identifier of a product

quantity
integer required
Default:
1
Example:
1
price
number

The unit price of the product. If specified, then the pricing strategy is not applied.

Example:
9.99
tax_amount
number
discount
Object
discount_amount
number
discount_percentage
number
discount_incl_tax
number
sub_total
number
notes
string

A note regarding the item

total_amount
number
total_discount_amount
number
total_discount_incl_tax
number
total_price
number
amount_due
number
tax_amount
number
net_amount
number

Responses

200 OK

The request has succeeded

Body
Object
id
string

The unique identifier of the Service Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/{id}/charges HTTP/1.1 

Content-Type: application/json

{
    "account_id": "",
    "discount": {
        "amount": 1,
        "type": "PERCENTAGE"
    },
    "line_items": [
        {
            "product_id": "",
            "quantity": 1,
            "price": 9.99,
            "tax_amount": 1,
            "discount": {
                "discount_amount": 1,
                "discount_percentage": 1,
                "discount_incl_tax": 1
            },
            "sub_total": 1,
            "notes": ""
        }
    ],
    "total_amount": 1,
    "total_discount_amount": 1,
    "total_discount_incl_tax": 1,
    "total_price": 1,
    "amount_due": 1,
    "tax_amount": 1,
    "net_amount": 1
}
Update Charges for Service Request
PUT /service_requests/{id}/charges

Updates products associated to a service request.

Path variables

id
string required

Service Request id

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string
discount
Object
amount
integer
Example:
1
type
string
Enumeration:
AMOUNT
PERCENTAGE
line_items
Array
Object
product_id
string
quantity
integer
Example:
1
price
number
Example:
9.99
notes
string
tax_amount
number
sub_total
number
discount
Object
discount_amount
number
discount_percentage
number
discount_incl_tax
number
total_amount
number
total_discount_amount
number
total_discount_incl_tax
number
total_price
number
amount_due
number
tax_amount
number
net_amount
number

Responses

200 OK

The request has succeeded

Body
Object
id
string

The unique identifier of the Service Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/service_requests/{id}/charges HTTP/1.1 

Content-Type: application/json

{
    "account_id": "",
    "discount": {
        "amount": 1,
        "type": "PERCENTAGE"
    },
    "line_items": [
        {
            "product_id": "",
            "quantity": 1,
            "price": 9.99,
            "notes": "",
            "tax_amount": 1,
            "sub_total": 1,
            "discount": {
                "discount_amount": 1,
                "discount_percentage": 1,
                "discount_incl_tax": 1
            }
        }
    ],
    "total_amount": 1,
    "total_discount_amount": 1,
    "total_discount_incl_tax": 1,
    "total_price": 1,
    "amount_due": 1,
    "tax_amount": 1,
    "net_amount": 1
}
Get Charges for invoicing on service request
GET /service_requests/{id}/charges

Retrieves the products associated to a service request

Path variables

id
string required

The id of the service request

Responses

200 OK
Body
Object
account
Object

The account that the charges are associated with

id
string
name
string
number
string
currency
string
discount
Object
amount
number
type
string
Enumeration:
PERCENTAGE
AMOUNT
line_items
Array
Object
product
Object

The id of the product.

id
string
sku
string
name
string
quantity
integer

The quantity of the product

Example:
1
price
number

The price of the product

Example:
9.99
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
notes
string
tax_amount
number
discount
Object
discount_amount
number
discount_percentage
number
discount_incl_tax
number
total_cost
number
net_amount
string
tax_amount
number
total_discount
Object
amount
number
amount_incl_tax
number
total_before_discount
number
amount_due
number
Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/{id}/charges HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "account": {
        "id": "",
        "name": "", 
        "number": ""
    },
    "currency": "",
    "discount": {
        "amount": 1,
        "type": "AMOUNT"
    },
    "line_items": [
        {
            "product": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "quantity": 1,
            "price": 9.99,
            "tax_model": "TAX_INCLUSIVE",
            "notes": "",
            "tax_amount": 1,
            "discount": {
                "discount_amount": 1,
                "discount_percentage": 1,
                "discount_incl_tax": 1
            }
        }
    ],
    "total_cost": 1,
    "net_amount": "",
    "tax_amount": 1,
    "total_discount": {
        "amount": 1,
        "amount_incl_tax": 1
    },
    "total_before_discount": 1,
    "amount_due": 1
}
Linked Requests
POST /service_requests/{id}/linked_requests
GET /service_requests/{id}/linked_requests
DELETE /service_requests/{id}/linked_requests/{link_id}
POST /service_requests/{id}/linked_requests

Create a new service request link

Path variables

id
string required

The GUID of the link between two service requests

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
linked_request_id
string GUID required

The GUID of the linked request

Example:
ABDF8727684768276FGHGDHC
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The GUID for the new service request

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/CAD1E31269B76D7A65ACCE45B2E68DFD/linked_requests HTTP/1.1 

Content-Type: application/json

[
    {
        "linked_request_id": "ABDF8727684768276FGHGDHC"
    }
]
GET /service_requests/{id}/linked_requests

Retrieve a link between service request and another

Path variables

id
string required

The GUID of the link

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string

The GUID of the linked service Request

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The ticket number of the linked service request.

Example:
SR0001GHJ
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/CAD1E31269B76D7A65ACCE45B2E68DFD/linked_request HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content":[
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "number": "SR0001GHJ"
        }    
    ]

}
DELETE /service_requests/{id}/linked_requests/{link_id}

Delete a single service request link to another.

Path variables

id
string GUID required

The GUID of the service request link to be deleted

Example:
4AD9C84FA60F9FE407140E20F707726A
link_id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/service_requests/4AD9C84FA60F9FE407140E20F707726A/linked_request/{link_id} HTTP/1.1 

HTTP/1.1 200 OK 
Notes
POST /service_requests/{id}/notes
PUT /service_requests/{id}/notes/{note_id}
DELETE /service_requests/{id}/notes/{note_id}
GET /service_requests/{id}/notes
Create Service Request Note
POST /service_requests/{id}/notes

Create a new note for a service request

Path variables

id
string required

Service Request GUID for which the note is to be created

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
note
string required

The note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
pinned
boolean

Pinned notes appear at the top of the notes list.

Example:
true
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The identifier for the note created

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/6A24D2B5E44F44B28451FE021FCAD51E/notes HTTP/1.1 

Content-Type: application/json

{
    "note": "After my telephone conversation with Zack this morning, it was decided that....",
    "pinned": true
}
Update Service Request Note
PUT /service_requests/{id}/notes/{note_id}

Update a note for a service request.

Path variables

id
string required

The service request GUID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
note_id
string required

The note GUID

Example:
SMA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
note
string

The actual note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
pinned
boolean

Pinned notes appear at the top of the notes list.

Example:
true
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the updated note

Example:
SMA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/service_requests/CAD1E31269B76D7A65ACCE45B2E68DFD/notes/SMA1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json

{
    "note": "After my telephone conversation with Zack this morning, it was decided that....",
    "pinned": true
}
Delete Service Request Note
DELETE /service_requests/{id}/notes/{note_id}

Delete a single note for a service request

Path variables

id
string GUID required

The GUID of the service request

Example:
PT19C84FA60F9FE407140E20F707726A
note_id
string required

The GUID of the note to be deleted

Example:
XOP9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/service_requests/PT19C84FA60F9FE407140E20F707726A/notes/XOP9C84FA60F9FE407140E20F707726A HTTP/1.1 
List Service Request Notes
GET /service_requests/{id}/notes

Retrieve all notes for a single service request

Path variables

id
string required

The GUID of the lead whose notes are to be retrieved

Example:
TFD1E31269B76D7A65ACCE45B2E68DFD

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The note unique identifier

Example:
LEP1E31269B76D7A65ACCE45B2E68D34
created_on
string epoch

Date and time the note was created

Example:
98765775
updated_on
string epoch

Date and time the note was updated

Example:
98765795
pinned
boolean

Pinned notes appear at the top of the notes list

Example:
true
note
string

The note contents

Example:
After my telephone conversation with Zack this morning, it was decided that....
created_by
Object

Details of the user who created the note

id
string

The GUID of the user who created the note

Example:
1121E31269B76D7A65ACCE45B2E68KP1
username
string

The name of the user who created the note

Example:
Sam Jackson
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/TFD1E31269B76D7A65ACCE45B2E68DFD/notes HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "LEP1E31269B76D7A65ACCE45B2E68D34",
            "created_on": "98765775",
            "updated_on": "98765795",
            "pinned": "true",
            "note": "After my telephone conversation with Zack this morning, it was decided that....",
            "created_by": {
                "id": "1121E31269B76D7A65ACCE45B2E68KP1",
                "username": "Sam Jackson"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Tags

This functionality relates to service request tags.

POST /service_requests/{id}/tags
DELETE /service_requests/{id}/tags/{tag_id}
GET /service_requests/{id}/tags
PUT /service_requests/{id}/tags
Add tags to service Request
POST /service_requests/{id}/tags

The following process adds a tag to a service request.

Path variables

id
string required

The service request GUID

Example:
HRDGSWRSFVSDSDBSDSSDDE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id

Example:
FDHNFDBR675765ghdh
Example 1
POST https://sandbox.crm.com/backoffice/v1/service_requests/HRDGSWRSFVSDSDBSDSSDDE/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "FDHNFDBR675765ghdh"
        }
    ]
}
Delete Service Request Tag
DELETE /service_requests/{id}/tags/{tag_id}

Deletes a tag on a product.

Path variables

id
string required

The id of the service request.

Example:
JFGJKSFGJFSGH
tag_id
string required

The id of the tag

Example:
KJDFHKJGFSJHG
Example 1
DELETE https://sandbox.crm.com/backoffice/v1/service_requests/JFGJKSFGJFSGH/tags/KJDFHKJGFSJHG HTTP/1.1 
Get tags for service requests
GET /service_requests/{id}/tags

The following process retrieves the tags for a service request

Path variables

id
string required

Responses

200 OK
Body
Object
content
Array
Object
tag_id
string

The id of the row associated to the service request and tag combination.

Example:
JGKJSGDKJGSKJG
id
string

the tag ID

Example:
JKGJHFSDJHGDSJHGA
name
string

Name of Tag

Example:
Maintenance
colour
string

Colour of tag

Example:
The colour of the tag
Example 1
GET https://sandbox.crm.com/backoffice/v1/service_requests/{id}/tags HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "tag_id": "JGKJSGDKJGSKJG",
            "id": "JKGJHFSDJHGDSJHGA",
            "name": "Maintenance",
            "colour": "The colour of the tag"
        }
    ]
}
Update tags for Service Requests
PUT /service_requests/{id}/tags

The following process updates tags to a service requests.

Path variables

id
string required

The service request GUID

Example:
JGJHSGHJAGJHG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
tags
Array

the content relating to the tag

Object
id
string

The tag id.

Example:
JKGSJGFKDGJKFGFSJK
Example 1
PUT https://sandbox.crm.com/backoffice/v1/service_requests/JGJHSGHJAGJHG/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "tags": [
        {
            "id": "JKGSJGFKDGJKFGFSJK"
        }
    ]
}
Spend Rule Conditions
POST /spend_conditions
GET /spend_conditions
GET /spend_conditions/{id}
Create Spend Conditions
POST /spend_conditions

Creates a spend condition group including product, timing and organisation conditions.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The spend condition name

Example:
Instant Rewards - Monday Only
organisations
Array nullable

Conditions based on organisations

Unique items: YES
Example:
[
    "6A24D2B5E44F44B28451FE021FCAD51E"
]
string GUID
Example:
6A24D2B5E44F44B28451FE021FCAD51E
products
Array nullable
Object
item_type
string required

Which product piece of information will be used as a condition; the product itself, it type or brand or family?

Enumeration:
PRODUCT
TYPE
BRAND
FAMILY
item_id
string GUID required

The unique identifier of the selected item type.

Example:
6A24D2B5E44F44B28451FE021FCAD51E
timings
Array nullable

Conditions based on time

Object
month
integer

The month as a condition (1-12)

Example:
1
day
string
Enumeration:
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
start_time
string
end_time
string
validity
Object required

Validity (from) condition

validity_type
string required

The award validity type

Enumeration:
SPECIFIC_DATE

Amount will be available to be spend from a specific date

PERIOD

Amount will be available to be spend from a specific period

NEXT_PURCHASE

Amount will be available to be spend from the next purchase

specific_date
integer epoch nullable

The valid from date (applicable for specific date validity type)

Example:
1590474228
period
integer nullable

The validity from period (applicable for period validity type)

Example:
2
period_unit
string nullable

The award validity period unit (applicable for period validity type)

Enumeration:
HOUR
DAY
MONTH
YEAR
expiration
Object required

Expiration (valid to) condition

expiration_type
string required

The award expiration type

Enumeration:
NEVER
SPECIFIC_DATE
PERIOD
MONTH_END
YEAR_END
specific_date
integer epoch nullable

The date that the amount expires (applicable for specific expiration type)

Example:
1590474228
period
integer nullable

The expiration period (applicable for period expiration type)

Example:
1
period_unit
string nullable

The award validity period unit (applicable for period validity type)

Enumeration:
HOUR
DAY
MONTH
YEAR

Responses

200 200

Successful Request

Body
Object
id
string GUID

The spend condition identifier

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/spend_conditions HTTP/1.1 

Content-Type: application/json

{
    "name": "Instant Rewards - Monday Only",
    "organisations": [
        "6A24D2B5E44F44B28451FE021FCAD51E"
    ],
    "products": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "id_type": "TYPE"
        }
    ],
    "timings": [
        {
            "month": 1,
            "day": 1,
            "start_time": "19:00",
            "end_time": "20:00"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c0d4712e-6688-4604-b3d6-d084e4d2dc05"
}
List Spend Conditions
GET /spend_conditions

Retrieves the spend conditions available with brief information

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The spend condition identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The spend condition name

Example:
Happy Hour
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/spend_conditions HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Happy Hour"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Spend Conditions
GET /spend_conditions/{id}

Retrieve details for a specific spend condition

Path variables

id
string GUID required

The spend condition (identifer) to be retrieved

Example:
c0d4712e-6688-4604-b3d6-d084e4d2dc05

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The spend conditions identifier

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The spend condition name

Example:
Happy Hour
organisations
Array

Conditions based on organisations

Object
id
string GUID

The organisation identifier

Example:
308ad557-90de-b56c-fe96-0819cdf8e4d8
name
string

The organisation name

Example:
X-CAFE
locations
Array

The locations of the specific organisation

Object

Information about the organisation’s location

name
string

The name of the location

Example:
Head Office
address_line_1
string

The address of the location

Example:
Elia Papakyriakou 21
address_line_2
string

Additional address information about the location

Example:
7 Tower Stars
state_province_county
string

The state/province/county of the location

Example:
Egkomi
town_city
string

The town/city of the location

Example:
Nicosia
postal_code
string

The postal code of the location

Example:
2415
country_code
string

The country code of the location

Example:
CY
lat
number

The latitude of the location

Example:
35.157115
lon
number

The longitude of the location

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies a location

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
type
string

The organisation type

Enumeration:
BUSINESS
MERCHANT
VENUE
products
Array
Object
item_type
string required

Which product piece of information will be used as a condition; the product itself, it type or brand or family?

Enumeration:
PRODUCT
TYPE
BRAND
FAMILY
Example:
PRODUCT
item_id
string GUID required

The unique identifier of the selected item type.

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The name of the entity e.g the product name or product type name

Example:
Support Service
description
string

The descirption of the entity.

Example:
24/7 Support to all users
timings
Array

Conditions based on time

Object
month
integer

The month as a condition (1-12)

Example:
1
day
string
Enumeration:
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
start_time
string
end_time
string
validity
Object

Valid (from) condition

validity_type
string

The award validity type

Enumeration:
SPECIFIC_DATE

Amount will be available to be spend from a specific date

PERIOD

Amount will be available to be spend from a specific period

NEXT_PURCHASE

Amount will be available to be spend from the next purchase

specific_date
integer epoch

The date that the amount will be valid (applicable for specific validity type)

Example:
1590474228
period
integer

The specific validity period (applicable for period validity type)

Example:
1
period_unit
string

The award validity period unit (applicable for period validity type)

Enumeration:
HOUR
DAY
MONTH
YEAR
expiration
Object

Expiration (valid to) condition

expiration_type
string

The award expiration type

Enumeration:
NEVER
SPECIFIC_DATE
PERIOD
MONTH_END
YEAR_END
specific_date
integer epoch

The date that the amount expires (applicable for specific expiration type)

Example:
1590474228
period
integer

The specific expiration period (applicable for period expiration type)

Example:
2
period_unit
string

The award validity period unit (applicable for period validity type)

Enumeration:
HOUR
DAY
MONTH
YEAR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/spend_conditions/c0d4712e-6688-4604-b3d6-d084e4d2dc05 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6A24D2B5E44F44B28451FE021FCAD51E", 
    "name": "Happy Hour",
    "organisations": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "X-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,
                    "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
                }
            ],
            "type": "BUSINESS"
        }
    ],
    "products": [
        {
            "item_type": "PRODUCT",
            "item_id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Support Service",
            "description": "24/7 Support to all users"
        }
    ],
    "timings": [
        {
            "month": 1,
            "day": "THURSDAY",
            "start_time": "",
            "end_time": ""
        }
    ]
}
Subscriptions
POST /subscriptions
PUT /subscriptions/{id}
GET /contacts/{id}/subscriptions
GET /subscriptions
GET /subscriptions/{id}
GET /contacts/{id}/services
GET /services/{id}/allowance
POST /subscriptions/{id}/services
POST /contacts/{id}/services
PUT /services/{id}
POST /subscriptions/{id}/devices
PUT /subscriptions/{id}/devices/{device_id}
GET /subscriptions/{id}/devices
GET /services/{id}/devices
POST /services/{id}/devices
POST /subsriptions/{id}/billing
GET /subscriptions/{id}/allowed_devices
POST /organisations/{id}/services
GET /organisations/{id}/services
Create Subscription
POST /subscriptions

Creates a new subscription for a contact

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
contact_id
string GUID nullable

Contacts unique identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
organisation_id
string nullable

The organisaton’s unique identifier. This is the organisation that owns the subscription

account_id
string GUID

The unique identifier of the contact’s account. If not specified, then the primary account is used

funding_source
string

The type of the event

Enumeration:
ACCOUNT

If one of the contact’s payment methods is specified as the subscription’s payment method as well, then the Account is considered as the funding source. The account is also the default funding source if no payment method is specified.

WALLET

The Wallet is the subscription’s funding source if subscriber specifically states that he/she wants to pay for the services using available wallet funds.

Default:
ACCOUNT
Example:
ACCOUNT
payment_method_id
string

One of the contact’s payment methods that will be used for automatically paying off the subscription

address
Object

The subscription’s address which must be one of the contact’s addresses. One of the two paramters must be specified

address_id
string nullable

The unique identifer of the contact’s address

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
use_primary
boolean nullable

If set to true, then the contac’t sprimary address will be selected as the new subscription’s address

Example:
true
billing_day
Object
day_of_month
string nullable
day_of_week
string nullable
billing_period
Object
duration
string nullable
uot
string nullable
Examples

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The GUID for the new subscription

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/subscriptions HTTP/1.1 

Content-Type: application/json

{
    "contact_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "organisation_id": "",
    "account_id": "",
    "funding_source": "ACCOUNT",
    "payment_method_id": "",
    "address": {
        "address_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "use_primary": "true"
    },
    "billing_day": {
        "day_of_month": "",
        "day_of_week": ""
    },
    "billing_period": {
        "duration": "",
        "uot": ""
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Subscription
PUT /subscriptions/{id}

Update the billing terms of a group of services. Services of the same billing period are grouped under the same subscription

Path variables

id
string GUID required

The subscription (identifier) that will be updated

Example:
ac5401c3-b2e6-2d99-171f-276084d97536

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required
Enumeration:
CHANGE_BILLING_DAY
CHANGE_BILLING_CYCLE
CHANGE_PAYMENT_METHOD
ACTIVATE
DEACTIVATE
CANCEL
REGRET
PAUSE
RESUME
UPDATE
category_id
string GUID nullable

The action’s category unique identifier

Example:
ac5401c3-b2e6-2d99-171f-276084d97536
scheduled_date
integer epoch
use_proposed_date
boolean
Default:
false
payment_method_id
string GUID nullable

One of the contact’s payment methods. Required when changing the payment preference of the subscription’s terms

Example:
ac5401c3-b2e6-2d99-171f-276084d97536
billing_day
Object

Required when changing the billing day of the subscription’s terms

day_of_week
string nullable

Applies for weekly subscriptions

Example:
MONDAY
day_of_month
integer nullable

Applies for subscriptions with billing cycles over a month

Example:
15
billing_period
Object

Required when changing the billing cycle of the subscription.

duration
string required

The duration of the new billing cycle

Example:
3
uot
string required

The billing cycle’s unit of time

Enumeration:
DAYS
WEEKS
MONTHS
YEARS
Default:
DAYS
Example:
DAYS
agreement_date
integer epoch

Required when changing the subscription’s terms

number_of_days
integer

Required when pausing all of the services of a subscription

address_id
string

The updated subscription’s address which must be one of the contact’s addresses. Applicable only when using the UPDATE action

custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
funding_source
string

The type of the event

Enumeration:
ACCOUNT

If one of the contact’s payment methods is specified as the subscription’s payment method as well, then the Account is considered as the funding source. The account is also the default funding source if no payment method is specified.

WALLET

The Wallet is the subscription’s funding source if subscriber specifically states that he/she wants to pay for the services using available wallet funds.

Default:
ACCOUNT
Example:
ACCOUNT

Responses

200 OK
Body
Object
id
string GUID

The new subscripton action’s unique identifier

Example:
ac5401c3-b2e6-2d99-171f-276084d97536
proposed_scheduled_date
integer epoch

A proposed date on which the requested changes can be scheduled

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/subscriptions/ac5401c3-b2e6-2d99-171f-276084d97536 HTTP/1.1 

Content-Type: application/json

{
    "action": "ACTIVATE",
    "category_id": "ac5401c3-b2e6-2d99-171f-276084d97536",
    "scheduled_date": 1,
    "use_proposed_date": "false",
    "payment_method_id": "ac5401c3-b2e6-2d99-171f-276084d97536",
    "billing_day": {
        "day_of_week": "MONDAY",
        "day_of_month": 15
    },
    "agreement_date": 1,
    "number_of_days": 1,
    "address_id": "",
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ac5401c3-b2e6-2d99-171f-276084d97536",
    "proposed_scheduled_date": 1
}
List Contact Subscriptions
GET /contacts/{id}/subscriptions

Returns a list of subscriptions owned by a specified contact

Path variables

id
string required

The contact’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_only_terminated
boolean optional

By default, Inactive subscriptions are excluded. Use this parameter to get a list of Inactive Subscriptions only.

include_billing_info
boolean optional

By default, billing information is not retunred

Default:
false
include_terms
string optional

By default billing terms are not returned

Default:
false
Example:
false

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The unique identifier of the subscription

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
code
string

The subscription’s code.

Example:
4347869878000989
life_cycle_state
string

The subscription’s life cycle state

Enumeration:
ACTIVE

There’s at elast one non-terminated service

INACTIVE

There are no services on the subscription or if services exist, they are all terminated

Example:
ACTIVE
active_services
integer

Number of active (non-terminated) services

Example:
3
number_of_devices
integer

Number of devices

Example:
1
first_activation_date
integer

The date on which the subscription was activated for the first time

Example:
1620981311
billing_info
Object

The date until which the subscription’s services are billed

rated_up_date
integer
next_billing_date
integer
next_payment_date
integer
one_time_services
boolean

Indicates whether the subscirpiton is sed to group together the one-time services purchased by the contact. Set to true it at least oe service was purchased and despite the fact that the service is expired

Example:
true
terms
Object

The subscription’s terms

billing_period
Object

The subscription’s billing cycle duration

duration
integer

The billing cycle’s duration

Example:
1
uot
string

The billing cycle’s unit of time

Example:
MONTHS
billing_day
Object

The day of month/week until which the subscripton’s services will be billed. Either a day of month or day of week is returned, depnding on the subscription’s billing cycle (if it is less than a month, then a day of week is returned)

day_of_month
integer

Day of month

Example:
1
day_of_week
string

Day of week

Enumeration:
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
usage_blocked
boolean

Determines whether usage is allowed to be consumed as part of at least one of the active services of the subscription. Usage might be allowed by one of the services, but at the time the Web API is triggered, the customer is blocked for consuming usage

Default:
false
Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/{id}/subscriptions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
            "code": "4347869878000989",
            "life_cycle_state": "ACTIVE",
            "active_services": 3,
            "number_of_devices": 1,
            "first_activation_date": 1620981311,
            "billing_info": {
                "rated_up_date": 1,
                "next_billing_date": 1,
                "next_payment_date": 1
            },
            "terms": {
                "billing_period": {
                    "duration": 1,
                    "uot": "MONTHS"
                },
                "billing_day": {
                    "day_of_month": 1,
                    "day_of_week": "SUNDAY"
                }
            },
            "usage_blocked": "true"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
List Subscriptions
GET /subscriptions

Returns a list of subscriptions

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_only_terminated
boolean optional

By default, Inactive subscriptions are excluded. Use this parameter to get a list of Inactive Subscriptions only.

first_activation_date
string optional

The date on which the subscriptions was activated for the first time. Each option includes the field name, the operator and the date field in epoch format. Use up to two of the following options based on the required search:

Enumeration:
first_activation_date.[gte]
first_activation_date.[gt]
first_activation_date.[lte]
first_activation_date.[lt]
expires_on
integer optional

The date on which one of the subscription’s services gets expired

next_renewal
integer optional

The date on which one of the subscription’s services will be renewed

contract_ends
integer optional

The date on which the contract of one of the subscription’s services ends

contact_id
string optional

The contact who owns the subscription

account_id
string optional

The account of the contact who ows the subscription

device_id
string optional

The device thatis provisioned by the subscriptions to be retrieved

include_billing_info
boolean optional

By default, the subscription’s billing details are not returned. Set the value to True to get the basic billing information

Default:
false
include_terms
boolean optional

By default, the subscription’s billing terms are not returned. Set the value to True to get the subscription’s billing day and period

Default:
false
search_value
string optional

Search for a subscription based on its code

funding_source
string optional
Enumeration:
ACCOUNT
WALLET
organisation_id
string optional

The organisation that owns the subscription

life_cycle_state
array of string optional

The life cycle state of the subscription

Collection format: csv
service_id
string optional

Termed service’s product identifier. Subscription must have such a non-churned termed service

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
code
string
life_cycle_state
string
Enumeration:
ACTIVE
INACTIVE
first_activation_date
integer
Example:
1620984119
active_services
integer
Example:
3
number_of_devices
integer
Example:
3
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
contact
Object
id
string
name
string
Example:
John Smith
code
string
Example:
12345
billing_info
Object
next_billing_date
integer
next_payment_date
integer
rated_up_date
integer
one_time_services
boolean
terms
Object
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
MONDAY
usage_blocked
boolean

Determines whether usage is allowed to be consumed as part of at least one of the active services of the subscription. Usage might be allowed by one of the services, but at the time the Web API is triggered, the customer is blocked for consuming usage

Default:
false
Example:
false
inactive_services
integer

Number of inactive services

Example:
2
draft_services
integer

Number of Draft services

Example:
1
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "code": "",
            "life_cycle_state": "INACTIVE",
            "first_activation_date": 1620984119,
            "active_services": 3,
            "number_of_devices": 3,
            "organisation": {
                "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
                "name": "Bravo Coffee"
            },
            "contact": {
                "id": "",
                "name": "John Smith",
                "code": "12345"
            },
            "billing_info": {
                "next_billing_date": 1,
                "next_payment_date": 1,
                "rated_up_date": 1,
                "one_time_services": true
            },
            "terms": {
                "billing_period": {
                    "duration": 1,
                    "uot": "MONTHS"
                },
                "billing_day": {
                    "day_of_month": 1,
                    "day_of_week": "MONDAY"
                }
            },
            "usage_blocked": "false",
            "inactive_services": 2,
            "draft_services": 1
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Subscription
GET /subscriptions/{id}

Returns detailed inormation for a subscription

Path variables

id
string required

The unique identifier of the subscription

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
code
string
life_cycle_state
string
Example:
ACTIVE
first_activation_date
integer
Example:
12345567
cancellation_date
integer
Example:
12345678
active_services
integer
Example:
3
number_of_devices
integer
Example:
1
billing_info
Object
rated_up_date
integer
Example:
1234567
next_billing_date
integer
Example:
1234567
next_payment_date
integer
Example:
12345671
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
contact
Object
id
string
name
string
Example:
John Smith
code
string
Example:
12345
account
Object
id
string
number
string
name
string
terms
Object
agreement_date
integer
Example:
12345678
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
MONDAY
payment_method
Object
id
string
type
string
Example:
CARD
last4
string
Example:
1234
brand
string
Example:
VISA
funding_type
string
Example:
PREPAID
funding_source
string

The type of the event

Enumeration:
ACCOUNT

If one of the contact’s payment methods is specified as the subscription’s payment method as well, then the Account is considered as the funding source. The account is also the default funding source if no payment method is specified.

WALLET

The Wallet is the subscription’s funding source if subscriber specifically states that he/she wants to pay for the services using available wallet funds.

Default:
ACCOUNT
Example:
ACCOUNT
address
Object
id
string GUID

The address identifier

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string

A short name to allow it to be easily recognised in a list

Example:
My house
is_primary
boolean

Defines whether the address is the primary one

Example:
true
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string

The address care of

Example:
n/a
usage_blocked
boolean

Determines whether usage is allowed to be consumed as part of at least one of the active services of the subscription. Usage might be allowed by one of the services, but at the time the Web API is triggered, the customer is blocked for consuming usage

Default:
false
Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "code": "",
    "life_cycle_state": "ACTIVE",
    "first_activation_date": 12345567,
    "cancellation_date": 12345678,
    "active_services": 3,
    "number_of_devices": 1,
    "billing_info": {
        "rated_up_date": 1234567,
        "next_billing_date": 1234567,
        "next_payment_date": 12345671
    },
    "organisation": {
        "id": "4248fab3-67d5-2eb1-eaf6-079ce18cd2ed",
        "name": "Bravo Coffee"
    },
    "contact": {
        "id": "",
        "name": "John Smith",
        "code": "12345"
    },
    "account": {
        "id": "",
        "number": "",
        "name": ""
    },
    "terms": {
        "agreement_date": 12345678,
        "billing_period": {
            "duration": 1,
            "uot": "MONTHS"
        },
        "billing_day": {
            "day_of_month": 1,
            "day_of_week": "MONDAY"
        },
        "payment_method": {
            "id": "",
            "type": "CARD",
            "last4": "1234",
            "brand": "VISA",
            "funding_type": "PREPAID"
        },
        "funding_source": "ACCOUNT"
    },
    "address": {
        "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
        "address_type": "ALTERNATIVE",
        "address_name": "My house",
        "is_primary": true,
        "address_line_1": "Elia Papakyriakou",
        "address_line_2": "7 Tower Stars",
        "state_province_county": "Egkomi",
        "town_city": "Nicosia",
        "postal_code": "2015",
        "country": "CYP",
        "lat": 35.157115,
        "lon": 33.313719,
        "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
        "care_of": "n/a"
    },
    "usage_blocked": "true"
}
List Contact Services
GET /contacts/{id}/services

Returns a list of services to which a customer subscribed to

Path variables

id
string required

The contact’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_only_terminated
boolean optional

By default, only active services are included. Use this parameter to get a list of terminated/removed services services only.

classification
string optional

Product classification of the subscription services to be retrieved. If not specified, all services are returned

Enumeration:
ONE_TIME
TERMED
EXPENSE
include_subscription
boolean optional

Determine whether subscription and its billing terms will additionally be inclded in the response. Default to false

Default:
false
Example:
true
subscription_id
string optional

Unique identifier of the subscription that groups services by their billing cycle

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
classification
string
Example:
TERMED_SERVICE
has_allowance
boolean

Determines if the service has usage allowance settings.

Example:
true
service
Object
id
string
life_cycle_state
string
Example:
EFFECTIVE
added_on
integer
Example:
1625555027
removed_on
integer
Example:
1625555027
first_activated_on
integer
Example:
1625555027
is_recurring_charge
boolean
Example:
true
product
Object
id
string
sku
string
name
string
classification
string
Example:
TERMED_SERVICE
type_composition
string
Example:
FLEXIBLE_BUNDLE
price
Object
id
string
price
number
Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
price_type
string
Example:
FIXED
billing_period
Object
duration
string
uot
string
rating
Object
state
string
Example:
PENDING
rated_from
integer
Example:
1625555027
rated_to
integer
Example:
1625555027
terms
Object
billing_model
string
Example:
PRE_BILL
auto_renew
boolean
Example:
true
in_contract
boolean
Example:
true
quantity
integer
contract_period
Object
duration
integer
Example:
18
uot
string
Example:
MONTHS
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
termed_period
Object
billing_cycles
integer
Example:
1
start_date
integer
Example:
1
end_date
integer
Example:
1
trial_period
Object
trial_state
string
Example:
IN_TRIAL
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
duration
integer
Example:
7
uot
string
Example:
DAYS
paused_period
Object
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
components
Array
Object
id
string
added_on
integer
Example:
1625555027
first_activated_on
integer
Example:
1625555027
in_contract
boolean
life_cycle_state
string
product
Object
id
string
sku
string
name
string
price
Object
price
number
Example:
9.99
currency
string
Example:
EUR
trial_period
Object
trial_state
string
Example:
IN_TRIAL
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
bundled_device
Object

Applicabe only for services bundled with a device (traceable physical good) that also exists on the subscription

id
string
serial_number
string
product
Object
id
string
sku
string
name
string
subscription
Object
id
string
code
string
terms
Object
agreement_date
integer
Example:
1625555027
funding_source
string

The type of the event

Enumeration:
ACCOUNT

If one of the contact’s payment methods is specified as the subscription’s payment method as well, then the Account is considered as the funding source. The account is also the default funding source if no payment method is specified.

WALLET

The Wallet is the subscription’s funding source if subscriber specifically states that he/she wants to pay for the services using available wallet funds.

Default:
ACCOUNT
Example:
ACCOUNT
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
WEDNESDAY
payment_method
Object
id
string
type
string
Example:
CARD
last4
string
Example:
1234
brand
string
Example:
VISA
funding_type
string

The type of the event

Enumeration:
CREDIT
DEBIT
PREPAID
Example:
CREDIT
integrations
Array
Object

Details about the integration

id
string GUID

The integration identifier

Example:
81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4
name
string

The integration name

Example:
UniFi
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/{id}/services HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "classification": "TERMED_SERVICE",
            "has_allowance": "true",
            "pendingchanges":"true",
            "next_Change_date":123231231,
            "service": {
                "id": "",
                "life_cycle_state": "EFFECTIVE",
                "added_on": 1625555027,
                "removed_on": 1625555027,
                "first_activated_on": 1625555027,
                "is_recurring_charge": true,
                "product": {
                    "id": "",
                    "sku": "",
                    "name": "",
                    "classification": "TERMED_SERVICE",
                    "type_composition": "FLEXIBLE_BUNDLE"
                },
                "price": {
                    "id": "",
                    "price": 9.99,
                    "currency": "EUR",
                    "tax_model": "TAX_INCLUSIVE",
                    "price_type": "FIXED",
                    "billing_period": {
                        "duration": "",
                        "uot": ""
                    }
                },
                "rating": {
                    "state": "PENDING",
                    "rated_from": 1625555027,
                    "rated_to": 1625555027
                },
                "terms": {
                    "billing_model": "PRE_BILL",
                    "auto_renew": true,
                    "in_contract": true,
                    "quantity": 1,
                    "contract_period": {
                        "duration": 18,
                        "uot": "MONTHS",
                        "start_date": 1625555027,
                        "end_date": 1625555027
                    },
                    "termed_period": {
                        "billing_cycles": 1,
                        "start_date": 1,
                        "end_date": 1
                    }
                },
                "trial_period": {
                    "trial_state": "IN_TRIAL",
                    "start_date": 1625555027,
                    "end_date": 1625555027,
                    "duration": 7,
                    "uot": "DAYS"
                },
                "paused_period": {
                    "start_date": 1625555027,
                    "end_date": 1625555027
                },
                "components": [
                    {
                        "id": "",
                        "added_on": 1625555027,
                        "first_activated_on": 1625555027,
                        "in_contract": true,
                        "life_cycle_state": "",
                        "product": {
                            "id": "",
                            "sku": "",
                            "name": ""
                        },
                        "price": {
                            "price": 9.99,
                            "currency": "EUR"
                        },
                        "trial_period": {
                            "trial_state": "IN_TRIAL",
                            "start_date": 1625555027,
                            "end_date": 1625555027
                        }
                    }
                ],
                "bundled_device": {
                    "id": "",
                    "serial_number": "",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                }
            },
            "subscription": {
                "id": "",
                "code": "",
                "terms": {
                    "agreement_date": 1625555027,
                    "funding_source": "ACCOUNT",
                    "billing_period": {
                        "duration": 1,
                        "uot": "MONTHS"
                    },
                    "billing_day": {
                        "day_of_month": 1,
                        "day_of_week": "WEDNESDAY"
                    },
                    "payment_method": {
                        "id": "",
                        "type": "CARD",
                        "last4": "1234",
                        "brand": "VISA",
                        "funding_type": "CREDIT"
                    }
                }
            },
            "integrations": [
                {
                    "id": "81ed6bcd-39ec-214c-5124-9e5ac6cb5dc4",
                    "name": "UniFi"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Service Allowance
GET /services/{id}/allowance

Returns the usage allowance provided through a termed/one-time service as well as the remaining usage

Path variables

id
string required

Responses

200 OK
Body
Object
cash_amounts
Object
currency_code
string
allowed
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
remaining
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
products_allowance
Array
Object
item_type
string
Example:
PRODUCT
item_id
string
name
string
measurement_unit
Object
id
string
name
string
display_name
string
cash_amounts
Object
allowed
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
remaining
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
currency_code
string
usage_amounts
Object
allowed
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
remaining
Object
per_transaction
number
Example:
9.99
per_day
number
Example:
19.99
per_billing_cycle
number
Example:
59.99
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/services/{id}/allowance HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "cash_amounts": { 
        "currency_code": "",
        "allowed": {
            "per_transaction": 9.99,
            "per_day": 19.99,
            "per_billing_cycle": 59.99
        },
        "remaining": {
            "per_transaction": 9.99,
            "per_day": 19.99,
            "per_billing_cycle": 59.99
        }
    },
    "products_allowance": [
        {
            "item_type": "PRODUCT",
            "item_id": "",
            "name": "",
            "measurement_unit": {
                "id": "",
                "name": "",
                "display_name": ""
            },
            "cash_amounts": {
                "allowed": {
                    "per_transaction": 9.99,
                    "per_day": 19.99,
                    "per_billing_cycle": 59.99
                },
                "remaining": {
                    "per_transaction": 9.99,
                    "per_day": 19.99,
                    "per_billing_cycle": 59.99
                },
                "currency_code": ""
            },
            "usage_amounts": {
                "allowed": {
                    "per_transaction": 9.99,
                    "per_day": 19.99,
                    "per_billing_cycle": 59.99
                },
                "remaining": {
                    "per_transaction": 9.99,
                    "per_day": 19.99,
                    "per_billing_cycle": 59.99
                }
            }
        }
    ]
}
Add Subscription Service
POST /subscriptions/{id}/services

Adds a new service on a subscription. Multiple services can be added within a single Web API call. Services are added as Effective on the subscription

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
services
Array required

List of service products that will be added on the subscription. At least one must be specified.

Min items: 1
Object
product_id
string required

The identifier of the product. Only products classified as Termed services can be added as subscription services.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

Required only when the service has multiple price terms. If a single price exist, then it is used by default. If a service has no prices at all, then the service is added on a subscription with no billing information/terms

Example:
edc0809f-ed91-4b68-b912-5bd6064d901e
quantity
integer
Default:
1
Example:
5
components
Array

Applicable and required when the service being added is a flexible bundle. At least one component should be specified.

Min items: 1
Unique items: YES
Object
product_id
string required

The identifier of the product that will be added as a component in the flexible bundle

Example:
2dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

The price terms of the product to be added as a component. Required only when the component has multiple price terms and if its price is not included in the bundles price. If a single price exist, then it is used by default. If a service has no prices at all, then the service is added on a subscription with no billing information/terms

Example:
32c0809f-ed91-4b68-b912-5bd6064d901e
scheduled_date
integer

The date on which the services are scheduled to be added on the subscription. If not specified, then services are immediatelly added.

Example:
1621236954
use_proposed_date
boolean

If due to business rules, the services canot be immedaitelly added as effectve on the subscription, this Web API will suggest a scheduled date. Set this paramters to True if the Web API’s proposed date will be autoamtically be used to schedule the addition of the service(s).

Default:
false
Example:
true
pass
Object

Promotion pass redeemed for subscription services

code
string

Promotion pass code

Example:
HPX68933209
otp
string

Pass code OTP (roadmapped)

Responses

200 OK
Body
Array
Object
id
string

The unique identifier of the new subscription action

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901f
proposed_scheduled_date
integer

A proposed scheduled date returned if the requested action cannot be performed immediatelly due to business rules. If a proposed date is specified, then use it in the next Web API call as the scheduled date

Example:
1625561942
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/services HTTP/1.1 

Content-Type: application/json

{
    "services": [
        {
            "product_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "price_terms_id": "edc0809f-ed91-4b68-b912-5bd6064d901e",
            "quantity": 5,
            "components": [
                {
                    "product_id": "2dc0809f-ed91-4b68-b912-5bd6064d901e",
                    "price_terms_id": "32c0809f-ed91-4b68-b912-5bd6064d901e"
                }
            ]
        }
    ],
    "scheduled_date": 1621236954,
    "use_proposed_date": true,
    "pass": {
        "code": "HPX68933209",
        "otp": ""
    }
}
Add Service to Contact
POST /contacts/{id}/services

Adds a new service for a contact.Multiple services can be added within a single Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
services
Array required
Min items: 1
Object
product_id
string required

The unique dentifier of the service

Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

Required only when the service has multiple price terms. If a single price exist, then it is used by default.

Example:
9dc0809f-ed91-4b68-b912-5bd6064d901a
components
Array

Applicable and mandatory only if the new service is a flexible bundle

Min items: 1
Unique items: YES
Object
product_id
string required

The identifier of the product that will be added as a component in the flexible bundle

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901f
price_terms_id
string

The price terms of the product to be added as a component. Required only when the component has multiple price terms and if its price is not included in the bundles price. If a single price exist, then it is used by default. If a service has no prices at all, then the service is added on a subscription with no billing information/terms

Example:
d1c0809f-ed91-4b68-b912-5bd6064d901c
quantity
integer
Default:
1
Example:
5
devices
Array

TO DO

Object
id
string
scheduled_date
integer
use_proposed_date
boolean
pass
Object

Promotion pass details related to subscription services

code
string

Promotion pass code

Example:
MDE52023874
otp
string

Pass OTP (roadmapped)

Responses

200 OK
Body
Array
Object
id
string

The unique identifier of the new subscription action

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901f
proposed_scheduled_date
integer
Example:
1625561889
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/contacts/{id}/services HTTP/1.1 

Content-Type: application/json

{
    "services": [
        {
            "product_id": "3dc0809f-ed91-4b68-b912-5bd6064d901e",
            "price_terms_id": "9dc0809f-ed91-4b68-b912-5bd6064d901a",
            "components": [
                {
                    "product_id": "3ac0809f-ed91-4b68-b912-5bd6064d901f",
                    "price_terms_id": "d1c0809f-ed91-4b68-b912-5bd6064d901c"
                }
            ],
            "quantity": 5
        }
    ],
    "scheduled_date": 1,
    "use_proposed_date": true,
    "pass": {
        "code": "MDE52023874",
        "otp": ""
    }
}
Update Service
PUT /services/{id}

Updates a single susbcription service. A service might change due to various reasons and multiple changes can be logged per Web API log:

  • Change the service’s state
  • Change the service with another service
  • Change the service’s price terms
  • Change the service’s quantity
  • Change a flex service’s components

Path variables

id
string required

The subscription service’s identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string

The type of the event

Enumeration:
ACTIVATE
DEACTIVATE
CANCEL
REGRET
PAUSE
RESUME
CHANGE_TERMS
Example:
ACTIVATE
category_id
string

The action’s category unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
scheduled_date
integer

The date on which the action is scheduled to be executed. If not specified, the action is immediatelly executed.

Example:
1659594284
use_proposed_date
boolean

Applicable when business rules enforce an action to be performed on a future scheduled date. Set this parameter to True to indirectly use the business rules’ proposed scheduled date without explicitly defining it

Example:
true
number_of_days
integer

Applicable and mandatory when pausig a service. Defines the paused period’s duration

Example:
5
quantity
integer

Applicable when changing the terms of a service OR changing/swapping services

Example:
5
price_terms_id
string

Change the service’s price with one of its applicable ones. A service’s price can be changed into a new set of price terms of the same or a different billing cycle

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
extend_by
Object

Applicable and required when extending the service termed period or the contract period

period
integer required
Example:
1
period_uot
string required
Enumeration:
DAYS
WEEKS
MONTHS
change_to_service
Object

Applicable and required when upgrading or downgrading a service

product_id
string required

The new service product to which the service will be changed with

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

Required when the new service has multiple price terms. If the new service product has a single price, then it will be used by default

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
components
Object

Applicable only when amending a service bundle. At least one components to be added or to be removed must be specified

added
Array nullable
Unique items: YES
Object
product_id
string

The service product identifier that will be included in the bundle

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

The price terms of the product to be added as a component. Required only when the component has multiple price terms and if its price is not included in the bundles price. If a single price exist, then it is used by default. If a service has no prices at all, then the service is added on a subscription with no billing information/terms

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
removed
Array nullable
Unique items: YES
Object
id
string

Service indetifier of the components to be removed

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
locations
Array

Locations at which the service is delivered to. This set of locatinos can only include the subscriber’s registered addresses

Unique items: YES
Object
id
string

The contact address unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The new subscripton action’s unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
proposed_scheduled_date
integer

A proposed date on which the requested changes can be scheduled to tbe executed.

Example:
1659594284
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/services/{id} HTTP/1.1 

Content-Type: application/json

{
    "action": "ACTIVATE",
    "category_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "scheduled_date": 1659594284,
    "use_proposed_date": true,
    "number_of_days": 5,
    "quantity": 5,
    "price_terms_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "extend_by": {
        "period": 1,
        "period_uot": "WEEKS"
    },
    "change_to_service": {
        "product_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
        "price_terms_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
    },
    "components": {
        "added": [
            {
                "product_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "price_terms_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
            }
        ],
        "removed": [
            {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
            }
        ]
    },
    "locations": [
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "proposed_scheduled_date": 1659594284
}
Add Subscription Device
POST /subscriptions/{id}/devices

Adds a new device on a subscription.Multiple devices can be added within a single Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
devices
Array required
Min items: 1
Object
device_id
string

The unique identifer of the device

price_terms_id
string

Responses

200 OK
Body
Object
id
string

The unique identifer of the subscription action that adds the device on a subscription

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/devices HTTP/1.1 

Content-Type: application/json

{
    "devices": [
        {
            "device_id": "",
            "price_terms_id": ""
        }
    ]
}
Update Subscription Device
PUT /subscriptions/{id}/devices/{device_id}

Updates a single susbcription device. The update removes the device from the subscription or replaces it with another one.

Path variables

id
string required

The unique identifier of the subscription

device_id
string required

The unique identifier of the Device

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required
Enumeration:
REMOVE

rename to RETURN

REPLACE
UPDATE

roadmap. Updates general service infromation like the custom fields

replaced_by
Object

Applicable and required when replacing a device. Eitehr an identifier or the serial number of the device can be specified.

device_id
string nullable

The unique identifer of the device

serial_number
string nullable

The device’s serial number

custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 OK
Body
Object
id
string

The new subscripton action’s unique identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/devices/{device_id} HTTP/1.1 

Content-Type: application/json

{
    "action": "REMOVE",
    "replaced_by": {
        "device_id": "",
        "serial_number": ""
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
List Subscription Devices
GET /subscriptions/{id}/devices

Returns a list of devices tha provision the services of a subscription

Path variables

id
string required

The subscription’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
added_on
integer
Example:
23131231232
enabled_services
integer

Number of services enabled on the device

device
Object
id
string
serial_number
string
Example:
STB3332222111
state
string
Example:
RENTAL
ownership
string
Example:
OWNED_BY_BUSINESS
provisioning
Object

The provisioning integrator, if applicable. Information dependes on the device’s product and its type

id
string

The integration’s unique identifier

name
string

the integration’s name e.g. Irdeto

product
Object
id
string
sku
string
name
string
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
electronic_id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/devices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "added_on": 23131231232,
            "enabled_services": 1,
            "device": {
                "id": "",
                "serial_number": "STB3332222111",
                "state": "RENTAL",
                "ownership": "OWNED_BY_BUSINESS",
                "provisioning": {
                    "id": "",
                    "name": ""
                },
                "product": {
                    "id": "",
                    "sku": "",
                    "name": ""
                },
                "custom_fields": [
                    {
                        "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a",
                        "key": "back_office",
                        "label": "Back Office",
                        "description": "The account's back office code",
                        "tooltip": "",
                        "enabled": true,
                        "visible": true,
                        "field": "RADIO_BUTTONS",
                        "entity": "ORGANISATIONS"
                    }
                ]
            }
        }
    ]
}
List Service Devices
GET /services/{id}/devices

Returns a list of devices on which the specified service is or could be enabled on

Path variables

id
string required

The service’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
state
integer

Defines whether the service is already enabled on the device or not. If disabled, then the service can be enable don the related device

Enumeration:
ENABLED
DISABLED
Example:
ENABLED
code
string

Unique code that relates the service and the device to which it is enabled on

Example:
4534440932322212
device
Object

The device on which the service is already or could be enabled on

id
string

the unique identifier of the device

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
serial_number
string

The device’s serial number

Example:
STB0001023222
product
Object

The product of the device

id
string

The unique dentifier of the product

Example:
2dc0809f-ed91-4b68-b912-5bd6064d901e
sku
string

The product’s SKU

Example:
STB001
name
string

The product’s name

Example:
Set-Top-Box
electronic_id
string
paging
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/services/{id}/devices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "state": "ENABLED",
            "device": {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "serial_number": "STB0001023222",
                "product": {
                    "id": "2dc0809f-ed91-4b68-b912-5bd6064d901e",
                    "sku": "STB001",
                    "name": "Set-Top-Box"
                }
            }
        }
    ]
}
Set Up Service Devices
POST /services/{id}/devices

Enables and/or disables a service on one or more devices.

Path variables

id
string required

The subscription’s unique identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
action
string

Define whether the service will be enabled or disabled on the specified device

Enumeration:
ENABLE
DISABLE
Example:
ENABLE
device_id
string

The unique identifier of the device

Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The unique identiier of the subscription action

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/devices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id":"",
            "added_on":23131231232,
            "device":{
                "id":"",
                "serial_number":"STB3332222111",
                "state":"RENTAL",
                "ownership":"OWNED_BY_BUSINESS",
                "product":{
                    "id":"",
                    "sku":"",
                    "name":""
                },
                "rental_price":{
                    "price":2.99,
                    "currency":"EUR",
                    "billing_period":{
                        "duration":1,
                        "uot":"MONTHS"
                    }
                }
            }
        }
    ]
}
Bill Upcoming billing cycles
POST /subsriptions/{id}/billing

Bills in advance a subscription for a number of upcoming billig cycles. Any scheduled changes planned within this period will be taken into account. In cases of exceeded credit limit, billing is successful only if it can also be paid using an online paymnt method or the CRM Wallet accordinly. Subscription services billed on a post-bill basis and usage service can never be billed in advance.

Path variables

id
string required

The subscription’s unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
upcoming_billing_cycles
integer

Number of billing cycles to bill in advance

Min: 1
Max: 24
Default:
1
Example:
3
bill_up_to_date
integer

The date up until which the subscirption will be billed. This date must be one of the future billing cycles’ start date i.e. it must be have the subscription’s billing date. This date however must be set within the next 24 months.

Example:
1689948097

Responses

201 Created
Body
Object
invoice_id
string

Invoice unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
credit_note_id
string

Credit Note unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/subsriptions/4dc0809f-ed91-4b68-b912-5bd6064d901e/billing HTTP/1.1 

Content-Type: application/json

{
    "upcoming_billing_cycles": 3,
    "bill_up_to_date": 1689948097
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "invoice_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
    "credit_note_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
}
List devices to be added on a subscription
GET /subscriptions/{id}/allowed_devices

Returns a list of devices that can be added on a subscription. The list includes devices already owned by the contact and devices owned by the business.

Path variables

id
string required

The subscription’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
ownership
string optional
Enumeration:
OWNED_BY_CONTACT
OWNED_BY_BUSINESS
search_value
string optional

Search for a device using its serial number

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
ownership
string

The ownership of the device

Enumeration:
OWNED_BY_CONTACT
OWNED_BY_BUSINESS
device
Object

The available device

id
string
serial_number
string
product
Object
id
string
sku
string
name
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/allowed_devices HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "ownership": "OWNED_BY_BUSINESS",
            "device": {
                "id": "",
                "serial_number": "",
                "product": {
                    "id": "",
                    "sku": "",
                    "name": ""
                }
            }
        }
    ]
}
Add Service to Organisation
POST /organisations/{id}/services

Adds a new service for an Organisation.Multiple services can be added within a single Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
services
Array required
Min items: 1
Object
product_id
string required

The unique dentifier of the service

Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e
price_terms_id
string

Required only when the service has multiple price terms. If a single price exist, then it is used by default.

Example:
9dc0809f-ed91-4b68-b912-5bd6064d901a
components
Array

Applicable and mandatory only if the new service is a flexible bundle

Min items: 1
Unique items: YES
Object
product_id
string required

The identifier of the product that will be added as a component in the flexible bundle

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901f
price_terms_id
string

The price terms of the product to be added as a component. Required only when the component has multiple price terms and if its price is not included in the bundles price. If a single price exist, then it is used by default. If a service has no prices at all, then the service is added on a subscription with no billing information/terms

Example:
d1c0809f-ed91-4b68-b912-5bd6064d901c
quantity
integer
Default:
1
Example:
5
scheduled_date
integer
use_proposed_date
boolean

Responses

200 OK
Body
Array
Object
id
string

The unique identifier of the new subscription action

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901f
proposed_scheduled_date
integer
Example:
1625561889
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/{id}/services HTTP/1.1 

Content-Type: application/json

{
    "services": [
        {
            "product_id": "3dc0809f-ed91-4b68-b912-5bd6064d901e",
            "price_terms_id": "9dc0809f-ed91-4b68-b912-5bd6064d901a",
            "components": [
                {
                    "product_id": "3ac0809f-ed91-4b68-b912-5bd6064d901f",
                    "price_terms_id": "d1c0809f-ed91-4b68-b912-5bd6064d901c"
                }
            ],
            "quantity": 5
        }
    ],
    "scheduled_date": 1,
    "use_proposed_date": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "3ac0809f-ed91-4b68-b912-5bd6064d901f",
        "proposed_scheduled_date": 1625561889
    }
]
List Organisation Services
GET /organisations/{id}/services

Returns a list of services to which an organisation subscribed to

Path variables

id
string required

The contact’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
include_only_terminated
boolean optional

By default, only active services are included. Use this parameter to get a list of terminated/removed services services only.

classification
string optional

Product classification of the subscription services to be retrieved. If not specified, all services are returned

Enumeration:
ONE_TIME
TERMED
EXPENSE
include_subscription
boolean optional

Determine whether subscription and its billing terms will additionally be inclded in the response. Default to false

Default:
false
Example:
true
subscription_id
string optional

Unique identifier of the subscription that groups services by their billing cycle

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
classification
string
Example:
TERMED_SERVICE
service
Object
id
string
life_cycle_state
string
Example:
EFFECTIVE
added_on
integer
Example:
1625555027
removed_on
integer
Example:
1625555027
first_activated_on
integer
Example:
1625555027
is_recurring_charge
boolean
Example:
true
product
Object
id
string
sku
string
name
string
classification
string
Example:
TERMED_SERVICE
type_composition
string
Example:
FLEXIBLE_BUNDLE
price
Object
id
string
price
number
Example:
9.99
currency
string
Example:
EUR
tax_model
string
Enumeration:
TAX_INCLUSIVE
TAX_EXCLUSIVE
price_type
string
Example:
FIXED
billing_period
Object
duration
string
uot
string
rating
Object
state
string
Example:
PENDING
rated_from
integer
Example:
1625555027
rated_to
integer
Example:
1625555027
terms
Object
billing_model
string
Example:
PRE_BILL
auto_renew
boolean
Example:
true
in_contract
boolean
Example:
true
quantity
integer
contract_period
Object
duration
integer
Example:
18
uot
string
Example:
MONTHS
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
termed_period
Object
billing_cycles
integer
Example:
1
start_date
integer
Example:
1
end_date
integer
Example:
1
trial_period
Object
trial_state
string
Example:
IN_TRIAL
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
duration
integer
Example:
7
uot
string
Example:
DAYS
paused_period
Object
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
components
Array
Object
id
string
added_on
integer
Example:
1625555027
first_activated_on
integer
Example:
1625555027
in_contract
boolean
life_cycle_state
string
product
Object
id
string
sku
string
name
string
price
Object
price
number
Example:
9.99
currency
string
Example:
EUR
trial_period
Object
trial_state
string
Example:
IN_TRIAL
start_date
integer
Example:
1625555027
end_date
integer
Example:
1625555027
bundled_device
Object

Applicabe only for services bundled with a device (traceable physical good) that also exists on the subscription

id
string
serial_number
string
product
Object
id
string
sku
string
name
string
subscription
Object
id
string
code
string
terms
Object
agreement_date
integer
Example:
1625555027
funding_source
string

The type of the event

Enumeration:
ACCOUNT

If one of the contact’s payment methods is specified as the subscription’s payment method as well, then the Account is considered as the funding source. The account is also the default funding source if no payment method is specified.

WALLET

The Wallet is the subscription’s funding source if subscriber specifically states that he/she wants to pay for the services using available wallet funds.

Default:
ACCOUNT
Example:
ACCOUNT
billing_period
Object
duration
integer
Example:
1
uot
string
Example:
MONTHS
billing_day
Object
day_of_month
integer
Example:
1
day_of_week
string
Example:
WEDNESDAY
payment_method
Object
id
string
type
string
Example:
CARD
last4
string
Example:
1234
brand
string
Example:
VISA
funding_type
string

The type of the event

Enumeration:
CREDIT
DEBIT
PREPAID
Example:
CREDIT
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organisations/{id}/services HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "classification": "TERMED_SERVICE",
            "service": {
                "id": "",
                "life_cycle_state": "EFFECTIVE",
                "added_on": 1625555027,
                "removed_on": 1625555027,
                "first_activated_on": 1625555027,
                "is_recurring_charge": true,
                "product": {
                    "id": "",
                    "sku": "",
                    "name": "",
                    "classification": "TERMED_SERVICE",
                    "type_composition": "FLEXIBLE_BUNDLE"
                },
                "price": {
                    "id": "",
                    "price": 9.99,
                    "currency": "EUR",
                    "tax_model": "TAX_INCLUSIVE",
                    "price_type": "FIXED",
                    "billing_period": {
                        "duration": "",
                        "uot": ""
                    }
                },
                "rating": {
                    "state": "PENDING",
                    "rated_from": 1625555027,
                    "rated_to": 1625555027
                },
                "terms": {
                    "billing_model": "PRE_BILL",
                    "auto_renew": true,
                    "in_contract": true,
                    "quantity": 1,
                    "contract_period": {
                        "duration": 18,
                        "uot": "MONTHS",
                        "start_date": 1625555027,
                        "end_date": 1625555027
                    },
                    "termed_period": {
                        "billing_cycles": 1,
                        "start_date": 1,
                        "end_date": 1
                    }
                },
                "trial_period": {
                    "trial_state": "IN_TRIAL",
                    "start_date": 1625555027,
                    "end_date": 1625555027,
                    "duration": 7,
                    "uot": "DAYS"
                },
                "paused_period": {
                    "start_date": 1625555027,
                    "end_date": 1625555027
                },
                "components": [
                    {
                        "id": "",
                        "added_on": 1625555027,
                        "first_activated_on": 1625555027,
                        "in_contract": true,
                        "life_cycle_state": "",
                        "product": {
                            "id": "",
                            "sku": "",
                            "name": ""
                        },
                        "price": {
                            "price": 9.99,
                            "currency": "EUR"
                        },
                        "trial_period": {
                            "trial_state": "IN_TRIAL",
                            "start_date": 1625555027,
                            "end_date": 1625555027
                        }
                    }
                ],
                "bundled_device": {
                    "id": "",
                    "serial_number": "",
                    "product": {
                        "id": "",
                        "sku": "",
                        "name": ""
                    }
                }
            },
            "subscription": {
                "id": "",
                "code": "",
                "terms": {
                    "agreement_date": 1625555027,
                    "funding_source": "ACCOUNT",
                    "billing_period": {
                        "duration": 1,
                        "uot": "MONTHS"
                    },
                    "billing_day": {
                        "day_of_month": 1,
                        "day_of_week": "WEDNESDAY"
                    },
                    "payment_method": {
                        "id": "",
                        "type": "CARD",
                        "last4": "1234",
                        "brand": "VISA",
                        "funding_type": "CREDIT"
                    }
                }
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Actions
GET /subscriptions/{id}/actions
GET /subscription_actions/{id}
PUT /subscription_actions/{id}
GET /subscriptions/{id}/allowed_actions
GET /services/{id}/allowed_actions
GET /contacts/{id}/actions
List Subscription Actions
GET /subscriptions/{id}/actions

Retrieves a list of subscription actions

Path variables

id
string required

Subscription unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
life_cycle_state
array of string optional
Collection format: csv
scheduled_date
integer optional
cancelled_date
integer optional
action_id
string optional

The ientifier of the subscription action

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
code
string
life_cycle_state
string
Enumeration:
EXECUTED
SCHEDULED
REJECTED
CANCELLED
behaviour_code
string
Enumeration:
REMOVE_SERVICE
business_classification_code
string
executed_on
integer
Example:
1234567
scheduled_on
integer
Example:
1234567
cancelled_on
integer
Example:
1234567
rejected_on
integer
Example:
1234567
category
Object
id
string
name
string
subscription
Object
id
string
code
string
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/actions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "code": "",
            "life_cycle_state": "",
            "behaviour_code": "",
            "business_classification_code": "",
            "executed_on": 1234567,
            "scheduled_on": 1234567,
            "cancelled_on": 1234567,
            "rejected_on": 1234567,
            "category": {
                "id": "",
                "name": ""
            },
            "subscription": {
                "id": "",
                "code": ""
            }
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Subscription Action
GET /subscription_actions/{id}

Retrieves detailed information of an existing subscription action

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
code
string
life_cycle_state
string
behaviour_code
string
business_classification_code
string
executed_on
integer
Example:
1234567
scheduled_on
integer
Example:
1234567
cancelled_on
integer
Example:
1234567
rejected_on
integer
Example:
1234567
rejection_reason
string
subscription
Object
id
string
code
string
category
Object
id
string
name
string
services
Array

A list of sevices affected by the subscription action

Object
change_type
string
Enumeration:
ADDED
REMOVED
UPDATED
product
Object
id
string
sku
string
name
string
quantity
number

The updated quantity of the service

Example:
2
price
Object

the service#s updated price. Applicable when changing a service’s terms

id
string

The price’s identifier

label
string

The price’s label

Example:
VIP Price
price
number
Example:
9.99
billing_period
Object
duration
number
Example:
1
uot
string
Example:
MONTHS
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscription_actions/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "code": "",
    "life_cycle_state": "",
    "behaviour_code": "",
    "business_classification_code": "",
    "executed_on": 1234567,
    "scheduled_on": 1234567,
    "cancelled_on": 1234567,
    "rejected_on": 1234567,
    "rejection_reason": "",
    "subscription": {
        "id": "",
        "code": ""
    },
    "category": {
        "id": "",
        "name": ""
    },
    "services": [
        {
            "change_type": "ADDED",
            "product": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "quantity": 2,
            "price": {
                "id": "",
                "label": "VIP Price",
                "price": 9.99,
                "billing_period": {
                    "duration": 1,
                    "uot": "MONTHS"
                }
            }
        }
    ]
}
Update Subscription Action
PUT /subscription_actions/{id}

Updates an existing subscripton action.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string
Enumeration:
CANCEL

Allowed only for Scheduled actions

RESUBMIT

Allowed only for Rejected actions

UPDATE

Allowed only for Scheduled actions

category_id
string
scheduled_date
integer

Applicable only for Scheduled actions

Example:
1234567
period_settings
Object

Applicable only for Scheduled actions

duration_in_days
integer
Example:
5
ends_on
integer
Example:
1234567

Responses

200 OK
Body
Object
id
string
proposed_scheduled_date
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/subscription_actions/{id} HTTP/1.1 

Content-Type: application/json

{
    "action": "UPDATE",
    "category_id": "",
    "scheduled_date": 1234567,
    "period_settings": {
        "duration_in_days": 5,
        "ends_on": 1234567
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "proposed_scheduled_date": ""
}
List Allowed Subscription Actions
GET /subscriptions/{id}/allowed_actions

Retrieves a list of subscription actions tha can be perofrmed on a specific subscription at a specific period of time

Path variables

id
string required

Request parameters

execution_date
integer optional

The date on which the subscription action will be executed. If not specified, the current date is considered

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
behaviour_code
string
business_classification_code
string
services
Array

A list of services that will be affected by the action

Object
id
string
product
Object
id
string
sku
string
name
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscriptions/{id}/allowed_actions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "behaviour_code": "",
    "business_classification_code": "",
    "services": [
        {
            "id": "",
            "product": {
                "id": "",
                "sku": "",
                "name": ""
            }
        }
    ]
}
List Allowed Subscription Service Actions
GET /services/{id}/allowed_actions

Retrieves a list of subscription actions that can be perofrmed on a specific services at a specific period of time

Path variables

id
string required

Request parameters

execution_date
integer optional

The date on which the subscription action will be executed. If not specified, the current date is considered

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
behaviour_code
string
business_classification_code
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/services/{id}/allowed_actions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "behaviour_code": "",
    "business_classification_code": ""
}
List Contact Actions
GET /contacts/{id}/actions

Retrieves a list of subscription actions performed for a contact

Path variables

id
string required

Unique identifier of a contact

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
state
array of string optional
Collection format: csv
scheduled_date
integer optional
cancelled_date
integer optional
action_id
string optional

The identifier of the subscription action

subscription_id
string optional

The identifier of the subscription

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
code
string
state
string
Enumeration:
EXECUTED
SCHEDULED
REJECTED
CANCELLED
behaviour_code
string
Enumeration:
REMOVE_SERVICE
business_classification_code
string
executed_on
integer
Example:
1234567
scheduled_on
integer
Example:
1234567
cancelled_on
integer
Example:
1234567
rejected_on
integer
Example:
1234567
category
Object
id
string
name
string
subscription
Object
id
string
code
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contacts/{id}/actions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id": "",
            "code": "",
            "state": "SCHEDULED",
            "behaviour_code": "REMOVE_SERVICE",
            "business_classification_code": "",
            "executed_on": 1234567,
            "scheduled_on": 1234567,
            "cancelled_on": 1234567,
            "rejected_on": 1234567,
            "category": {
                "id": "",
                "name": ""
            },
            "subscription": {
                "id": "",
                "code": ""
            }
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Service Locations
PUT /services/{id}/locations
GET /services/{id}/locations
Update Service Locations
PUT /services/{id}/locations

Updates the locations at which the service is used/consumed

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
locations
Array

A list of contact addresses that represent the various locations at which a service is being used/consumed. At least one address must be specified and must be one of the subscription owner’s addresses.

Object
id
string

A contact address unique identifier.

Example:
1ac0809f-ed91-4b32-b912-5b45064d90af

Responses

200 OK
Body
Object
id
string

The subscription service’s unique identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/services/{id}/locations HTTP/1.1 

Content-Type: application/json

{
    "locations": [
        {
            "id": "1ac0809f-ed91-4b32-b912-5b45064d90af"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Get Service Locations
GET /services/{id}/locations

Returns a list of locations at which a service is being used/consumed. This is a set of addresses of the contact who owns the subscription service

Path variables

id
string required

The service’s unique identifier

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The address identifier

Example:
0df9936c-7d5f-a878-4c05-9b942aa14295
address_type
string

The address type. Many of the same type.

Enumeration:
HOME
BUSINESS
ALTERNATIVE
address_name
string

A short name to allow it to be easily recognised in a list

Example:
My house
is_primary
boolean

Defines whether the address is the primary one

Example:
true
address_line_1
string

The address line 1

Example:
Elia Papakyriakou
address_line_2
string

The address line 2

Example:
7 Tower Stars
state_province_county
string

The address state/province/county

Example:
Egkomi
town_city
string

The address town/city

Example:
Nicosia
postal_code
string

The address postal code

Example:
2015
country
string

The address country (based on ISO 3 char code)

Example:
CYP
lat
number

The latitude of the address

Example:
35.157115
lon
number

The longitude of the address

Example:
33.313719
google_place_id
string

The Google textual identifier that uniquely identifies an address

Example:
ChIJrTLr-GyuEmsRBfy61i59si0
care_of
string

The address care of

Example:
n/a
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/services/{id}/locations HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "0df9936c-7d5f-a878-4c05-9b942aa14295",
            "address_type": "BUSINESS",
            "address_name": "My house",
            "is_primary": true,
            "address_line_1": "Elia Papakyriakou",
            "address_line_2": "7 Tower Stars",
            "state_province_county": "Egkomi",
            "town_city": "Nicosia",
            "postal_code": "2015",
            "country": "CYP",
            "lat": 35.157115,
            "lon": 33.313719,
            "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
            "care_of": "n/a"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Topups
POST /topups
GET /topups/{id}
Create Topup
POST /topups

Create a new top-up transaction for a specific account or wallet.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
account_id
string GUID required nullable

The account unique identification for which the topup will be performed. Either account or wallet is applicable and mandatory

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
wallet_id
string GUID required nullable

The wallet unique identification for which the topup will be performed. Either account or wallet is applicable and mandatory

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
payment_method
string

The type of the event

Enumeration:
CARD
CASH
Example:
CARD
payment_method_id
string GUID

The ID of the actual payment method, if any. Applicable only when the wallet is toped-up using a Card

Example:
e283a863-18e1-7cae-48c4-7433bf28cf97
code
string

A unique 16-digit code, will be auto-generated if not provided

Example:
1234567891234567
topup_date
integer epoch

Date of Topup Request

Example:
1618298816
amount
number

The amount of the topup. This amoun is in the wallet’s currency

Example:
9.99
spend_condition_id
string

Group of conditions that define how the top up’s amount can be spent. Specifying spend conditions will move the money to the wallet’s Commerce balance otherwise, money goes to Open balance.

Example:
f283a863-18e1-7cae-48c4-7433bf28cf97
custom_fields
Array nullable
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The top-up unique identifier

Example:
2b98beb3-df11-f14d-561b-a93fcd4a246a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Wallet Top-Up

Cash Top-Up for a specific Wallet

POST https://sandbox.crm.com/backoffice/v1/topups HTTP/1.1 

Content-Type: application/json

{
    "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "wallet_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "payment_method": "CASH",
    "payment_method_id": "e283a863-18e1-7cae-48c4-7433bf28cf97",
    "code": "1234567891234567",
    "topup_date": 1618298816,
    "amount": 9.99,
    "spend_condition_id": "f283a863-18e1-7cae-48c4-7433bf28cf97"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "2b98beb3-df11-f14d-561b-a93fcd4a246a"
}
Get Topup
GET /topups/{id}

Retrieve details of an existing topup transaction

Path variables

id
string GUID required

The unique identifier of the topup to be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
code
string

The code of the topup transaction

Example:
1234567891234567
life_cycle_state
string

The life cycle state of the topup transaction

Enumeration:
POSTED
topup_date
integer epoch

The creation date of the topup. Defaults to the current date

Example:
1583846865
amount
number

The amount of the topup

Example:
9.99
currency_code
string

The topup’s currency code

Example:
EUR
contact
Object

The contact for which the topup was performed

id
string GUID

The unique ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The full name of the contact that owns the topup

Example:
John Johnson
code
string

The unique code of the contact that owns the topup

Example:
C123
account
Object

The account for which the topup was performed. Either account or wallet is applicable.

id
string GUID

The unique ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The unique number

Example:
AC123456
wallet
Object

The wallet for which the topup was performed. Either account or wallet is applicable.

id
string GUID

The unique ID

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
code
string

The unique code

Example:
123456AAVV123685
payment_method
string

The type of the event

Enumeration:
CARD
CASH
Example:
CARD
payment_method_id
string

Unique identifier of the contact/organisation payment method. Applicable only if the payment method type is Card

Example:
a283a863-18e1-7cae-48c4-7433bf28cf97
payment_method_details
Object

The card’s main information. Required and applicable if the payment method type is CARD

brand
string

The card’s brand

Example:
VISA
first6
string

The first 6 digits of the card. Either the card number or the first 6 and last 4 digits must be specified

last4
string

The last 4 digits f the card. Either the card number or the first 6 and last 4 digits must be specified

expiration_month
integer

The card expiration month

Example:
1
expiration_year
integer

The card expiration year

Example:
2020
spend_condition
Object

The group of conditions that show how the top up’s amount can be spend.

id
string

The unique identifier of the spend condition

Example:
a283a863-18e1-7cae-48c4-7433bf28cf97
name
string

The name of the spend condition

Example:
TV Services
custom_fields
Array
Object
key
string

The custom field’s unique key

Example:
back_office
value
string

The custom field’s value

Example:
0001-12345
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/topups/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "code": "1234567891234567", 
    "life_cycle_state": "POSTED",
    "topup_date": 1583846865,
    "amount": 9.99,
    "currency_code": "EUR",
    "contact": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "name": "John Johnson",
        "code": "C123"
    },
    "account": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "number": "AC123456"
    },
    "wallet": {
        "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "code": "123456AAVV123685"
    },
    "payment_method": "CARD",
    "payment_method_id": "a283a863-18e1-7cae-48c4-7433bf28cf97",
    "payment_method_details": {
        "brand": "VISA",
        "first6": "",
        "last4": "",
        "expiration_month": 1,
        "expiration_year": 2020
    },
    "spend_condition": {
        "id": "a283a863-18e1-7cae-48c4-7433bf28cf97",
        "name": "TV Services"
    },
    "custom_fields": [
        {
            "key": "back_office",
            "value": "0001-12345"
        }
    ]
}
Transfers
POST /transfers
GET /transfers/{id}
Create Transfer
POST /transfers

Create a new Transfer between accounts, wallets or account and wallet

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
origin
Object required

The origin of the transfer. Can be either an account or a wallet

account_id
string GUID nullable

Source account unique id

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
wallet_id
string GUID nullable

Source wallet unique id

Example:
A65ACCE45B2E68DFDCAD1E31269B76D7
destination
Object required

The destination of the transfer. Can be either an account or a wallet

account_id
string GUID nullable

Destination account unique id

Example:
CE45B2E68DFDCAD1E31269B76D7A65AC
wallet_id
string GUID nullable

Destination wallet unique id

Example:
B76D7A65ACCCAD1E31269E45B2E68DFD
transfer_date
number epoch

date of transfer

Example:
1620999582
amount
number

Transfer amount. the amount is in the origin entity’s currency.

Example:
9.99
code
string

A unique 16-digit code, will be auto-generated if not provided

Example:
1234567891234567
spend_condition_id
string

Applicable only when transfering funds to a wallet. If specified, then the amount will be transfered to the wallet’s Commerce Balance and reserved to be spent based on the conditions. Otheewise, money is transferred to the wallet’s Open balance

Example:
B76D7A65ACCCAD1E31269E45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the transfer

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/transfers HTTP/1.1 

Content-Type: application/json

{
    "origin": {
        "account_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
        "wallet_id": "A65ACCE45B2E68DFDCAD1E31269B76D7"
    },
    "destination": {
        "account_id": "CE45B2E68DFDCAD1E31269B76D7A65AC",
        "wallet_id": "B76D7A65ACCCAD1E31269E45B2E68DFD"
    }, 
    "transfer_date": 1620999582,
    "amount": 9.99,
    "code": "1234567891234567",
    "spend_condition_id": "B76D7A65ACCCAD1E31269E45B2E68DFD"
}
Get Transfer
GET /transfers/{id}

Get details of an existing transfer transaction

Path variables

id
string GUID required

The unique identifier of the transfer to be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
code
string

The transfer code

Example:
1234567891234567
life_cycle_state
string

The life cycle state of the transfer

Enumeration:
POSTED
transfer_date
integer

Date of transfer

amount
number

Transfer amount

Example:
9.99
origin
Object

The origin of the transfer. Can be either an account or a wallet. Information about the Contact is retrieved in either case

account
Object nullable

Origin account details

id
string GUID

The unique ID of the source account

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
number
string

The unique number of the source account

Example:
AC123456
wallet
Object nullable

Origin wallet details

id
string GUID

The unique ID of the source wallet

Example:
D7A65ACCE45BCAD1E31269B762E68DFD
code
string

The unique code of the source wallet

Example:
W123456AA
contact
Object

Details of the source contact

id
string GUID

Contact’s unique ID

Example:
1269B76D7A65ACCE4CAD1E35B2E68DFD
name
string

The full name of the contact that originated the transfer

Example:
John Smith
code
string

The unique code of the contact that originated the transfer

Example:
C1230955623
destination
Object

The destination of the transfer. Can be either an account or a wallet. Information about the Contact is retrieved in either case

account
Object nullable

Destination account details

id
string GUID

Destination account unique ID

Example:
76D7A65ACCE45B2E68DFDCAD1E31269B
number
string

Destination account unique number

Example:
AC123456
wallet
Object nullable

Destination wallet details

id
string GUID

Destiantion wallet unique ID

Example:
CD7A65ACCE45B2E68DFDAD1E31269B76
code
string

Destiantion wallet unique code

Example:
W321456AA
contact
Object

Destiantion contact’s details

id
string GUID

Destination contact’s unique ID

Example:
E68DFDCAD1E37A65ACCE45B21269B76D
name
string

The full name of the contact that the transfer was sent to

Example:
Janet Smith
code
string

The unique code of the contact that the transfer was sent to

Example:
C1249044512
currency_code
string

The transfer currency, defaults to the origin account currency

Example:
EUR
spend_condition
Object

The group of conditions that define how the transfered amount can be spend. Applicable only when trasnfering money to a wallet.

id
string

The unique identifier fo the spend condition

Example:
E68DFDCAD1E37A65ACCE45B21269B76D
name
string

The name of the spend condition

Example:
TV services
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/transfers/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "code": "1234567891234567",
    "life_cycle_state": "POSTED",
    "transfer_date": 1,
    "amount": 9.99,
    "origin": {
        "account": {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "number": "AC123456"
        },
        "wallet": {
            "id": "D7A65ACCE45BCAD1E31269B762E68DFD",
            "code": "W123456AA"
        },
        "contact": {
            "id": "1269B76D7A65ACCE4CAD1E35B2E68DFD",
            "name": "John Smith",
            "code": "C1230955623"
        }
    },
    "destination": {
        "account": {
            "id": "76D7A65ACCE45B2E68DFDCAD1E31269B",
            "number": "AC123456"
        },
        "wallet": {
            "id": "CD7A65ACCE45B2E68DFDAD1E31269B76",
            "code": "W321456AA"
        },
        "contact": {
            "id": "E68DFDCAD1E37A65ACCE45B21269B76D",
            "name": "Janet Smith",
            "code": "C1249044512"
        }
    },
    "currency_code": "EUR",
    "spend_condition": {
        "id": "E68DFDCAD1E37A65ACCE45B21269B76D",
        "name": "TV services"
    }
}
Usage
POST /usage_records/
POST /usage_records/bulk
PUT /usage_records/{id}
DELETE /usage_records/{id}
GET /usage_records
GET /usage_records/{id}
Add Usage Records
POST /usage_records/

Creates a single usage record within a single call. Usage is consumed because contact has purchased a termed or a one-time service. So in cases where usage is recorded for a usage service without a reference to the termed/one-time service, CRM.COM might record the usage against one or more termed/one-time services, starting from the oldest and shortest one-time services. Consuming usage against a termed service has lower priority.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
usage_service_id
string required

The usage service being consumed. Only identifiers of products classified as Usage services can be specified.

Example:
897f0809f-ed91-4b68-b912-5bd6064ade12
usage_amount
number required

The consumed usage amount. The amount is specified in the usage service’s measurement unit.

Example:
1.99
usage_timestamp
integer

When the uage was consumed and recorded in CRM.COM

Example:
1637318444
consumer_identity
Object required

Who is the consuming usage. Usage is consumed by either a contact or an organisation. At least one of the parameters must be specified in order to successfully identify the contact

contact_id
string

The contact’s unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
organisation_id
string

The organisation’s identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
code
string

Contact code

Example:
C00000100123
mac_address
string

The MAC address of the device that is owned by the contact

Example:
00-D0-56-F2-B5-12
phone_number
string

The contact’s phone number

Example:
003579976766555
subscription_id
string

The unique identifier of the subscription

Example:
65fa809f-ed91-4b68-b912-5b23464d9acb
processing
string required

Defines whether the usage record’s processing will be performed ynchronously (at the time tha tis logged) or asynchronously. In the latter case, the usage record’s processing result can be sent back to the caller via Webhooks.

Enumeration:
SYNC
ASYNC
Example:
SYNC
charged_amount
number

How much the usage costs. Applicable in cases where usage is rated by the 3rd party system that records usage. In these cases, CRM.COM does not apply any additional pricing and usage is billed as provided. Promotions however might be applied, if any.

Example:
1.99
currency_code
string

The currency in which usage’s cost is recorded

Example:
EUR
service_id
string

The service through which usage is consumed. This is one of the contact’s service which is either classified as a termed or a one-time service. If not specified, then CRM.COM will record usage starting from the oldest and shortest one-time service (if any) and then from the termed service

Example:
00af0809f-ed91-4b68-b912-5bd60643253d
organisation_id
string

The organisation at which usage was consumed.

Example:
601a809f-ed91-4b68-b912-5b23464deac7
duration
Object

The usage’s duration (start and end time)

from
integer

The starting time of usage consuption

Example:
1650264327
to
integer

The end time of usage consuption

Example:
1650264339
destination
string

roadmap

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/usage_records/ HTTP/1.1 

Content-Type: application/json

{
    "usage_service_id": "897f0809f-ed91-4b68-b912-5bd6064ade12",
    "usage_amount": 1.99,
    "usage_timestamp": 1637318444,
    "consumer_identity": {
        "contact_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
        "organisation_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
        "code": "C00000100123",
        "mac_address": "00-D0-56-F2-B5-12",
        "phone_number": "003579976766555",
        "subscription_id": "65fa809f-ed91-4b68-b912-5b23464d9acb"
    },
    "processing": "SYNC",
    "charged_amount": 1.99,
    "currency_code": "EUR",
    "service_id": "00af0809f-ed91-4b68-b912-5bd60643253d",
    "organisation_id": "601a809f-ed91-4b68-b912-5b23464deac7",
    "duration": {
        "from": 1650264327,
        "to": 1650264339
    },
    "destination": ""
}

HTTP/1.1 204 No Content 
Add Usage Records Bulk
POST /usage_records/bulk

Creates multiple usage records within a single call. Usage is consumed because contact has purchased a termed or a one-time service. So in cases where usage is recorded for a usage service without a reference to the termed/one-time service, CRM.COM might record the usage against one or more termed/one-time services, starting from the oldest and shortest one-time services. Consuming usage against a termed service has lower priority.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
usage_service_id
string required

The usage service being consumed. Only identifiers of products classified as Usage services can be specified.

Example:
897f0809f-ed91-4b68-b912-5bd6064ade12
usage_amount
number required

The consumed usage amount. The amount is specified in the usage service’s measurement unit.

Example:
1.99
usage_timestamp
integer

When the uage was consumed and recorded in CRM.COM

Example:
1637318444
consumer_identity
Object required

Who is the contact or organisation consuming usage. At least one of the parameters must be specified in order to successfully identify the contact/organisation

contact_id
string nullable

The contact’s unique identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
organisation_id
string nullable

The organisation consuming usage

Example:
65fa809f-ed91-4b68-b912-5b23464d9acb
code
string nullable

Contact code

Example:
C00000100123
mac_address
string nullable

The MAC address of the device that is owned by the contact

Example:
00-D0-56-F2-B5-12
phone_number
string nullable

The contact’s phone number

Example:
003579976766555
subscription_id
string

The unique identifier of the contact’s subscription

Example:
65fa809f-ed91-4b68-b912-5b23464d9acb
charged_amount
number

How much the usage costs. Applicable in cases where usage is rated by the 3rd party system that records usage. In these cases, CRM.COM does not apply any additional pricing and usage is billed as provided. Promotions however might be applied, if ay.

Example:
1.99
currency_code
string

The currency in which usage’s cost is recorded

Example:
EUR
service_id
string

The service through which usage is consumed. This is one of the contact’s service which is either classified as a termed or a one-time service. If not specified, then CRM.COM will record usage starting from the oldest and shortest one-time service (if any) and then from the termed service

Example:
00af0809f-ed91-4b68-b912-5bd60643253d
organisation_id
string

The organisation at which usage was consumed.

Example:
601a809f-ed91-4b68-b912-5b23464deac7
duration
Object

The usage’s duration (start and end time)

from
integer

The starting time of usage consuption

Example:
1650264327
to
integer

The end time of usage consuption

Example:
1650264339
destination
string

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/usage_records/bulk HTTP/1.1 

Content-Type: application/json

[
    {
        "usage_service_id": "897f0809f-ed91-4b68-b912-5bd6064ade12",
        "usage_amount": 1.99,
        "usage_timestamp": 1637318444,
        "consumer_identity": {
            "contact_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "organisation_id": "65fa809f-ed91-4b68-b912-5b23464d9acb",
            "code": "C00000100123",
            "mac_address": "00-D0-56-F2-B5-12",
            "phone_number": "003579976766555",
            "subscription_id": "65fa809f-ed91-4b68-b912-5b23464d9acb"
        },
        "charged_amount": 1.99,
        "currency_code": "EUR",
        "service_id": "00af0809f-ed91-4b68-b912-5bd60643253d",
        "organisation_id": "601a809f-ed91-4b68-b912-5b23464deac7",
        "duration": {
            "from": 1650264327,
            "to": 1650264339
        },
        "destination": ""
    }
]

HTTP/1.1 204 No Content 
Update Usage Record
PUT /usage_records/{id}

Updates a single usage record.

Path variables

id
string required

Unique identifier of the usage record

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
state
string required nullable

Usage record’s state

Enumeration:
POSTED
REJECTED
CANCELLED
billing_state
string required nullable

Usage record’s blling state

Enumeration:
PENDING
COMPLETED
billing_directive
string required nullable

Usage record’s billing directive

Enumeration:
TO_BE_BILLED
TO_BE_CREDITED
NOT_TO_BE_BILLED

Responses

200 OK
Body
Object
id
string

The unique identifier of the usage record

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/usage_records/4dc0809f-ed91-4b68-b912-5bd6064d901e HTTP/1.1 

Content-Type: application/json

{
    "state": "CANCELLED",
    "billing_state": "COMPLETED",
    "billing_directive": "NOT_TO_BE_BILLED"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
}
Delete Usage Record
DELETE /usage_records/{id}

Deletes a single usage record

Path variables

id
string GUID required

The usage record (identifier) that will be deleted

Example:
cab35653-05ac-de36-5c64-1fbffbe3abfd

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/usage_records/cab35653-05ac-de36-5c64-1fbffbe3abfd HTTP/1.1 

HTTP/1.1 204 No Content 
List Usage Records
GET /usage_records

Retuns a list of usage records

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
contact_id
string optional
subscription_id
string optional
service_id
string optional

The unique identifier of the termed subscrpiton service or contact one-time service

usage_service_id
string optional

The unique identifier of the usage product

usage_timestamp
string optional

Filter based on the usage date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. usage_timestamp[gte]=1618395497&usage_timestamp[lt]=1618395497).

Enumeration:
usage_timestamp[gte]
usage_timestamp[gt]
usage_timestamp[lte]
usage_timestamp[lt]
organisation_id
string optional

The oganisation consuming usage

state
string optional
Enumeration:
POSTED
CANCELLED
REJECTED
billing_state
string optional
Enumeration:
PENDING
COMPLETED
billing_directive
string optional
Enumeration:
TO_BE_BILLED
NOT_TO_BE_BILLED
TO_BE_CREDITED
invoice_id
string optional

The invoice in which the usage records were included

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
code
string
usage_amount
number
Example:
1.99
usage_timestamp
integer
Example:
12345678
charged_amount
number
Example:
1.99
currency
string
Example:
EUR
state
string
Enumeration:
POSTED
REJECTED
CANCELLED
billing_state
string
Enumeration:
PENDING
COMPLETED
billing_directive
string
Enumeration:
TO_BE_BILLED
NOT_TO_BE_BILLED
TO_BE_CREDITED
contact
Object
id
string
code
string
name
string
usage_service
Object
id
string
sku
string
name
string
service
Object
id
string
sku
string
name
string
classification
string
Enumeration:
TERMED_SERVICE
ONE_TIME_SERVICE
measurement_unit
Object
id
string
name
string
display_name
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/usage_records?contact_id=123 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "code": "",
            "usage_amount": 1.99,
            "usage_timestamp": 12345678,
            "charged_amount": 1.99,
            "currency": "EUR",
            "state": "CANCELLED",
            "billing_state": "COMPLETED",
            "billing_directive": "TO_BE_CREDITED",
            "contact": {
                "id": "",
                "code": "",
                "name": ""
            },
            "usage_service": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "service": {
                "id": "",
                "sku": "",
                "name": "",
                "classification": "ONE_TIME_SERVICE"
            },
            "measurement_unit": {
                "id": "",
                "name": "",
                "display_name": ""
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Usage Record
GET /usage_records/{id}

Returns detailed information of a usage record. A single usage record is returned per Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
code
string
state
string
Enumeration:
POSTED
REJECTED
CANCELLED
billing_state
string
Enumeration:
PENDING
COMPLETED
billing_directive
string
Enumeration:
TO_BE_BILLED
NOT_TO_BE_BILLED
TO_BE_CREDITED
usage_timestamp
integer
Example:
1637320345
charged_amount
number
Example:
9.99
currency
string
Example:
EUR
usage_amount
number
Example:
1.99
usage_service
Object
id
string
sku
string
name
string
measurement_unit
Object
id
string
name
string
display_name
string
service
Object
id
string
sku
string
name
string
classification
string
Enumeration:
TERMED_SERVICE
ONE_TIME_SERVICE
contact
Object
id
string
code
string
name
string
Example:
John Smith
subscription
Object
id
string
code
string
organisation
Object
id
string
type
string
Example:
MERCHANT
name
string
Example:
merchant name
cancellation
Object

Applicable and mandatory only if a usage record is cancelled. Provides information on the user and the date on whiche the usage record was cancelled.

date
integer
user
Object
id
string
username
string
financials
Object
invoice
Object
id
string
number
string
credit_note
Object
id
string
number
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/usage_records/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "code": "",
    "state": "REJECTED",
    "billing_state": "COMPLETED",
    "billing_directive": "NOT_TO_BE_BILLED",
    "usage_timestamp": 1637320345,
    "charged_amount": 9.99,
    "currency": "EUR",
    "usage_amount": 1.99,
    "usage_service": {
        "id": "",
        "sku": "",
        "name": ""
    },
    "measurement_unit": {
        "id": "",
        "name": "",
        "display_name": ""
    },
    "service": {
        "id": "",
        "sku": "",
        "name": "",
        "classification": "ONE_TIME_SERVICE"
    },
    "contact": {
        "id": "",
        "code": "",
        "name": "John Smith"
    },
    "subscription": {
        "id": "",
        "code": ""
    },
    "organisation": {
        "id": "",
        "type": "MERCHANT",
        "name": "merchant name"
    },
    "cancellation": {
        "date": 1,
        "user": {
            "id": "",
            "username": ""
        }
    },
    "financials": {
        "invoice": {
            "id": "",
            "number": ""
        },
        "credit_note": {
            "id": "",
            "number": ""
        }
    }
}
Users & Authentication
POST /users/authenticate
GET /users/oidc
POST /users/refresh
POST /users/forgot_password
POST /users/change_password
POST /users/{id}/mode
POST /users/otp
POST /users/validate-otp
POST /users/{id}/sign_out
Authenticate User
POST /users/authenticate

Authenticate a user and provide a token to be used for subsequent API calls

Request headers

api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
username
string required nullable

The credential’s username

Example:
johndoe@crm.com
password
string required nullable

The credential’s password

Example:
password1234
two_factor_method
Object nullable

The user’s two-factor method that will be used during authentication (used only if user enabled two-factor authentication)

method
string required

The two-factor method

Enumeration:
BACKUP_CODE
TOTP
value
string required

The two-factor method value (applicable only for email, phone and back-up code based two-factor methods)

Example:
jo****@crm.com
token
string required nullable

The token taken from the oAUTH service provider (used if username/password not specified)

Example:
688a21ad-f082-e936
state
string required nullable

The state taken from the oAUTH service provider (used if username/password not specified)

Example:
e9c435c6-60f4-fa08-2396-6b3e7188a30e

Responses

200 200

OK

Body
Object

Authentication information provided for an admin user

access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw
refresh_token
string

The token that can be used to generate a new access token

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w
expiration_date
integer epoch

The token expiration date

Example:
1579880629
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
email
string

The user’s email address

Example:
johndoe@crm.com
mode
string

The organisation mode that the user was last signed into

Enumeration:
TRIAL

Organisation was not live enabled

TEST

Organisation is in test mode (therefore User is signed in test mode)

LIVE

Organisation supports live mode (therefore User is signed in live mode)

organisations
Array

The organisations that the user is joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
CLOUD_OPERATOR
SERVICE_OWNER
ORGANISATION
name
string

The organisation name

Example:
CRMdotCOM
is_primary
boolean

Defines the primary organisation that the user has joined

Example:
true
status
string

The organisation status

Enumeration:
ACTIVE
INACTIVE
SUSPEND
progress
Object

The organisation progress status

invite_user
boolean

Defines whether a user (other than the owner) is invited

Example:
true
create_contact
boolean

Defines whether a contact is created

Example:
false
create_reward_scheme
boolean

Defines whether a reward scheme is created

Example:
true
create_reward_offer
boolean

Defines whether a reward offer is created

Example:
false
create_merchant
boolean

Defines whether a merchant is created (applicable only for Business organisation)

Example:
false
create_venue
boolean

Defines whether a venue is created

Example:
false
password_expired
boolean

Defines whether password has been expired or not

Example:
true
lockout_date
integer epoch

Defines the date on which the user’s lockout will be expired

Example:
1615897181
two_factor_required
boolean

The two-factor method that is used and all user’s (configured) two-factor methods

Example:
true
two_factor_methods
Object

The two-factor method that is used and all user’s (configured) two-factor methods

send_method
Object

The method that is used for the two-factor authentication

method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
options
Array

The user’s (configured) two-factor methods

Object
method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
password_notification
integer

Defines the number of days that are left until password is expired

Example:
12
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/users/authenticate HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "username": "johndoe@crm.com",
    "password": "password1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw",
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w",
    "expiration_date": 1579880629,
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@crm.com",
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "ORGANISATION",
            "name": "CRMdotCOM"
        }
    ],
    "progress": {
        "invite_user": "true",
        "create_contact": "false",
        "create_reward_offer": "false",
        "create_merchant": "false",
        "create_venue": "false"
    }
}
OIDC User Authentication
GET /users/oidc

Authenticate a user over to an OIDC provider

Request parameters

username
string required

The user’s username that will be used for OIDC purposes

Example:
johndoe@crm.com

Request headers

api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 OK

The request has succeeded

Body
Object
authorization_url
string

The URL that users should be redirected for OIDC authentication purposes

Example:
azure.crm.com
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/users/oidc?username=johndoe@crm.com HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "authorization_url": "azure.crm.com"
}
Refresh User
POST /users/refresh

Provide authentication information using a refresh token that can be used in subsequent API calls

Request headers

authorization
string optional

The refresh token

Example:
Bearer eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

OK

Body
Object

Authentication information provided for an admin user

access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw
refresh_token
string

The token that can be used to generate a new access token

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w
expiration_date
integer epoch

The token expiration date

Example:
1579880629
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
email
string

The user’s email address

Example:
johndoe@crm.com
mode
string

The organisation mode that the user was last signed into

Enumeration:
TRIAL

Organisation was not live enabled

TEST

Organisation is in test mode (therefore User is signed in test mode)

LIVE

Organisation supports live mode (therefore User is signed in live mode)

organisations
Array

The organisations that the user is joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
CLOUD_OPERATOR
SERVICE_OWNER
ORGANISATION
name
string

The organisation name

Example:
CRMdotCOM
is_primary
boolean

Defines the primary organisation that the user has joined

Example:
true
status
string

The organisation status

Enumeration:
ACTIVE
INACTIVE
SUSPEND
progress
Object

The organisation progress status

invite_user
boolean

Defines whether a user (other than the owner) is invited

Example:
true
create_contact
boolean

Defines whether a contact is created

Example:
false
create_reward_scheme
boolean

Defines whether a reward scheme is created

Example:
true
create_reward_offer
boolean

Defines whether a reward offer is created

Example:
false
create_merchant
boolean

Defines whether a merchant is created (applicable only for Business organisation)

Example:
false
create_venue
boolean

Defines whether a venue is created

Example:
false
password_expired
boolean

Defines whether password has been expired or not

Example:
true
lockout_date
integer epoch

Defines the date on which the user’s lockout will be expired

Example:
1615897181
two_factor_required
boolean

The two-factor method that is used and all user’s (configured) two-factor methods

Example:
true
two_factor_methods
Object

The two-factor method that is used and all user’s (configured) two-factor methods

send_method
Object

The method that is used for the two-factor authentication

method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
options
Array

The user’s (configured) two-factor methods

Object
method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
password_notification
integer

Defines the number of days that are left until password is expired

Example:
12
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/users/refresh HTTP/1.1 

refresh_token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhMjc4ZDNlNS05YjhlLTQzNmUtOTIzMC03MGYzZTJkZjFjYTUiLCJleHAiOjE1Njg1NTQxMjJ9.LemqPPThkqfakkKS6CdkNvV1Lnc88CWirEpHOPnWjJPQz02zgkKSwfbvrEsl3OmR2LUhDILsOXf4x-GPFmNJCg

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw",
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w",
    "expiration_date": 1579880629,
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@crm.com",
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "BUSINESS",
            "name": "CRMdotCOM"
        }
    ],
    "progress": {
        "invite_user": "true",
        "create_contact": "false",
        "create_reward_offer": "false",
        "create_merchant": "false",
        "create_venue": "false"
    }
}
Forgot Password
POST /users/forgot_password

Request a new password for an existing user (providing the user’s login email address, where such password reset email will be sent)

Request headers

api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
email
string required

The email that will be used to request a new password

Example:
jd@crm.com

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/forgot_password HTTP/1.1 

Content-Type: application/json
api_key: 8c54d563-b991-4b76-8a83-557c08166f95

{
    "email": "jd@crm.com"
}

HTTP/1.1 200 OK 
Change Password
POST /users/change_password

Changes the password for a user (when a user requested a new one via Forgot Password)

Request body

Object
token
string required

The token that will verify that the client is trusted

Example:
ABCTKN123456798VGP2020
password
string required

The user’s new password

Example:
password1234

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/change_password HTTP/1.1 

Content-Type: application/json

{
    "token": "ABCTKN123456798VGP2020",
    "password": "password1234"
}

HTTP/1.1 200 OK
Switch Users Mode
POST /users/{id}/mode

Switch the user mode between test and live

Path variables

id
string GUID required

The user (identifer) that its mode will be changed

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

OK

Body
Object

Authentication information provided for an admin user

access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw
refresh_token
string

The token that can be used to generate a new access token

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w
expiration_date
integer epoch

The token expiration date

Example:
1579880629
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
email
string

The user’s email address

Example:
johndoe@crm.com
mode
string

The organisation mode that the user was last signed into

Enumeration:
TRIAL

Organisation was not live enabled

TEST

Organisation is in test mode (therefore User is signed in test mode)

LIVE

Organisation supports live mode (therefore User is signed in live mode)

organisations
Array

The organisations that the user is joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
CLOUD_OPERATOR
SERVICE_OWNER
ORGANISATION
name
string

The organisation name

Example:
CRMdotCOM
is_primary
boolean

Defines the primary organisation that the user has joined

Example:
true
status
string

The organisation status

Enumeration:
ACTIVE
INACTIVE
SUSPEND
progress
Object

The organisation progress status

invite_user
boolean

Defines whether a user (other than the owner) is invited

Example:
true
create_contact
boolean

Defines whether a contact is created

Example:
false
create_reward_scheme
boolean

Defines whether a reward scheme is created

Example:
true
create_reward_offer
boolean

Defines whether a reward offer is created

Example:
false
create_merchant
boolean

Defines whether a merchant is created (applicable only for Business organisation)

Example:
false
create_venue
boolean

Defines whether a venue is created

Example:
false
password_expired
boolean

Defines whether password has been expired or not

Example:
true
lockout_date
integer epoch

Defines the date on which the user’s lockout will be expired

Example:
1615897181
two_factor_required
boolean

The two-factor method that is used and all user’s (configured) two-factor methods

Example:
true
two_factor_methods
Object

The two-factor method that is used and all user’s (configured) two-factor methods

send_method
Object

The method that is used for the two-factor authentication

method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
options
Array

The user’s (configured) two-factor methods

Object
method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
password_notification
integer

Defines the number of days that are left until password is expired

Example:
12
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/mode HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw",
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w",
    "expiration_date": 1579880629,
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@crm.com",
    "mode": "LIVE",
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "CLOUD_OPERATOR",
            "name": "CRMdotCOM",
            "mode": "LIVE"
        }
    ],
    "progress": {
        "invite_user": "true",
        "create_contact": "false",
        "create_reward_scheme": "true",
        "create_reward_offer": "false",
        "create_merchant": "false",
        "create_venue": "false"
    }
}
Request One Time Password
POST /users/otp

Request an one-time password for a specific user. The request will check the user details and send an outbound validation number that can be used to verify the contact

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
credentials
Array required

Information on how the user will be identified

Object
name
string required

The predetermined information that will be used to identify the user

Enumeration:
TFA_EMAIL

Two-factor Authentication based on Email

TFA_PHONE

Two-factor Authentication based on Phone (SMS)

value
string required

The value of the credential to check

Example:
j_ioannou@crm.com

Responses

200 200

OK

Body
Object
auth_otp
string

The one time password auth otp id

Example:
0e5efc4e-5dc7-ea54-cf9d-498914806e0f
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/otp HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "credentials": [
        {
            "name": "TFA_EMAIL",
            "value": "j_ioannou@crm.com"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "auth_otp": "0e5efc4e-5dc7-ea54-cf9d-498914806e0f"
}
Validate One Time Password
POST /users/validate-otp

Verify an one-time password that was requested and provide authentication information that can be used for subsequent API calls

Request headers

api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
credentials
Array required

Information on how the user will be identified

Object
name
string required

User identification credentials

Enumeration:
TFA_OTP

Two-factor Authentication Auth Id

value
string required

The value of the credential to verify the user’s authenticity

Example:
ABC-123
code
integer required

The OTP code that should be used for verification purposes

Example:
123456

Responses

200 200

OK

Body
Object

Authentication information provided for an admin user

access_token
string

The token that can be used in subsequent API calls

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw
refresh_token
string

The token that can be used to generate a new access token

Example:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w
expiration_date
integer epoch

The token expiration date

Example:
1579880629
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
email
string

The user’s email address

Example:
johndoe@crm.com
mode
string

The organisation mode that the user was last signed into

Enumeration:
TRIAL

Organisation was not live enabled

TEST

Organisation is in test mode (therefore User is signed in test mode)

LIVE

Organisation supports live mode (therefore User is signed in live mode)

organisations
Array

The organisations that the user is joined

Object
external_id
string GUID

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78
org_type
string

The organisation type

Enumeration:
CLOUD_OPERATOR
SERVICE_OWNER
ORGANISATION
name
string

The organisation name

Example:
CRMdotCOM
is_primary
boolean

Defines the primary organisation that the user has joined

Example:
true
status
string

The organisation status

Enumeration:
ACTIVE
INACTIVE
SUSPEND
progress
Object

The organisation progress status

invite_user
boolean

Defines whether a user (other than the owner) is invited

Example:
true
create_contact
boolean

Defines whether a contact is created

Example:
false
create_reward_scheme
boolean

Defines whether a reward scheme is created

Example:
true
create_reward_offer
boolean

Defines whether a reward offer is created

Example:
false
create_merchant
boolean

Defines whether a merchant is created (applicable only for Business organisation)

Example:
false
create_venue
boolean

Defines whether a venue is created

Example:
false
password_expired
boolean

Defines whether password has been expired or not

Example:
true
lockout_date
integer epoch

Defines the date on which the user’s lockout will be expired

Example:
1615897181
two_factor_required
boolean

The two-factor method that is used and all user’s (configured) two-factor methods

Example:
true
two_factor_methods
Object

The two-factor method that is used and all user’s (configured) two-factor methods

send_method
Object

The method that is used for the two-factor authentication

method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
options
Array

The user’s (configured) two-factor methods

Object
method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor method obfuscated value (applicable only for email and phone based two-factor methods)

Example:
jo****@crm.com
password_notification
integer

Defines the number of days that are left until password is expired

Example:
12
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/validate-otp HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "credentials": [
        {
            "name": "TFA_OTP",
            "value": "ABC-123"
        }
    ],
    "code": 123456
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoiYWNjZXNzIiwicHJpbWFyeU9yZ2FuaXNhdGlvbiI6IjhkY2MzNjgwLTBiOGEtMTFlYS05NTE4LTQyMDEwYTlhMDAwMyIsImN1cnJlbnRPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJzY29wZSI6WyJjdXN0b21lci13cml0ZSIsIm9yZGVyLXJlYWQiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiamQiLCJlbWFpbCI6ImpkQGNybS5jb20iLCJleHAiOjE1Nzk4ODA2Mjl9.-uJyEW-Y_QgHb1q-WHBBMew3J_TnUfvqy-NDFmIzFhbS3gkerE5QAqp4cgNMr5BiGcyt174UVhYGXp2Fg7BKcw",
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhY2U5ZDRkMi0wYjhkLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJ0eXBlIjoicmVmcmVzaCIsInByaW1hcnlPcmdhbmlzYXRpb24iOiI4ZGNjMzY4MC0wYjhhLTExZWEtOTUxOC00MjAxMGE5YTAwMDMiLCJjdXJyZW50T3JnYW5pc2F0aW9uIjoiOGRjYzM2ODAtMGI4YS0xMWVhLTk1MTgtNDIwMTBhOWEwMDAzIiwic2NvcGUiOlsiY3VzdG9tZXItd3JpdGUiLCJvcmRlci1yZWFkIl0sInByZWZlcnJlZF91c2VybmFtZSI6ImpkIiwiZW1haWwiOiJqZEBjcm0uY29tIiwiZXhwIjoxNTc5ODgwNjI5fQ.cW_g6ozy2OaP5Tx3l2QuzNeRBSXnNrP1AN6QoOqf6s95eVoUrld6bHRUdBt3H74CZyrxhp7Rs_uXtv17GhVz5w",
    "expiration_date": 1579880629,
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@crm.com",
    "mode": "TRIAL",
    "organisations": [
        {
            "external_id": "QWERTY12345671234567324ETFTGBY78",
            "org_type": "SERVICE_OWNER",
            "name": "CRMdotCOM"
        }
    ],
    "progress": {
        "invite_user": "true",
        "create_contact": "false",
        "create_reward_scheme": "true",
        "create_reward_offer": "false",
        "create_merchant": "false",
        "create_venue": "false"
    },
    "password_token": "ABCDEFGH123456789",
    "lockout_date": 1615897181,
    "tfa_methods": [
        {
            "id": "3aa0ce8a-7307-5cec-9cdc-9e651e04916e",
            "method": "PHONE",
            "obfuscated": "j*****oe@crm.com"
        }
    ]
}
Sign Out User
POST /users/{id}/sign_out

Terminates the user’ session and will no longer be able to access the client (SPA)

Path variables

id
string GUID required

The user (identifer) that will be signed out

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/users/CAD1E31269B76D7A65ACCE45B2E68DFD/sign_out HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Users
POST /users/invite
POST /users/accept_invite
PUT /users/{id}
PUT /users/{id}/my_profile
DELETE /users/{id}
GET /users
GET /users/{id}
GET /users/{id}/my_profile
GET /users/organisations
POST /users/{id}/activate
POST /users/{id}/deactivate
POST /users/{id}/invite_resend
POST /users/verify_resend
DELETE /users/{id}/invite_revoke
POST /users/{id}/media_groups
POST /users/{id}/actions
Invite new User
POST /users/invite

Invite a new user to an organisation with a specific role (invitation will be sent via the specified email)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
organisation_id
string GUID required

The organisation identifier that the user is invited to

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
first_name
string required

The user’s first name

Example:
Jane
last_name
string required

The user’s last name

Example:
Doe
role_id
string GUID required

The user role

Example:
AUR1E31269B76D7A65ACCE45B2E68DFD
identity
Object required

The user’s identity

provider
string required

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string required

The identity challenge

Example:
jd@crm.com
teams
Array nullable

The teams that the user will be part of

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/invite HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "organisation_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "first_name": "Jane",
    "last_name": "Doe",
    "role_id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
    "identity": {
        "type": "EMAIL",
        "identity_challenge": "jd@crm.com"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Accept Invitation
POST /users/accept_invite

Accept a user’s invitation for joining an organisation

Request body

Object
token
string required

The token that will verify that the client is trusted

Example:
ABCTKN123456798VGP2020
password
string required

The user’s password

Example:
password1234

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/accept_invite HTTP/1.1 

Content-Type: application/json

{
    "token": "ABCTKN123456798VGP2020",
    "password": "password1234"
}

HTTP/1.1 200 OK
Update User
PUT /users/{id}

Update an existing user

Path variables

id
string GUID required

The user identifier that will be updated

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
first_name
string nullable

The user’s first name

Example:
Jane
last_name
string nullable

The user’s last name

Example:
Doe
role_id
string GUID nullable

The user role

Example:
UR1234567890123456789012345678
preferred_language
string nullable

The language preferred by the user for communication

Example:
EN
software_language
string nullable

The language preferred by the user for software translation

Example:
EN
contact_info
Array nullable

Information about the user’s contact details

Object
id
string GUID required nullable

The identifier of the user’s contact detail

Example:
CK1234567890123456789012345678
name
string nullable

The name of the user’s contact detail

Example:
Work
type
string required nullable

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string required nullable

The value of the user’s contact detail

Example:
janedoe@crm.com
teams
Array nullable

The teams that the user will be part of

Unique items: YES
string GUID
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /users/CK1234567890123456789012345678 HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "first_name": "Jane",
    "last_name": "Doe",
    "role_id": "UR1234567890123456789012345678",
    "contact_info": [
        {
            "id": "CK1234567890123456789012345678",
            "name": "Work",
            "type": "EXTENSION",
            "value": "janedoe@crm.com"
        }
    ],
    "teams": [
        "CAD1E31269B76D7A65ACCE45B2E68DFD"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update User - My Profile
PUT /users/{id}/my_profile

Update the signed-in user details

Path variables

id
string GUID required

The (signed-in) user (identifer) that will be updated

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
first_name
string nullable

The user’s first name

Example:
Jane
last_name
string nullable

The user’s last name

Example:
Doe
preferred_language
string nullable

The language preferred by the user for communications

Example:
EN
software_language
string nullable

The language preferred by the user for software translation

Example:
EN
contact_info
Array nullable

Information about the user’s contact details

Object
id
string GUID required nullable

The identifier of the user’s contact detail

Example:
CK1234567890123456789012345678
name
string nullable

The name of the user’s contact detail

Example:
Work
type
string required nullable

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string required nullable

The value of the user’s contact detail

Example:
janedoe@crm.com

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/users/CK1234567890123456789012345678/my_profile HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "first_name": "Jane",
    "last_name": "Doe",
    "preferred_language": "EN",
    "contact_info": [
        {
            "id": "CK1234567890123456789012345678",
            "name": "Work",
            "type": "PHONE",
            "value": "janedoe@crm.com"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete User
DELETE /users/{id}

Delete a user from a specific organisation

Path variables

id
string GUID required

The user (identifer) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

The user will be deleted only from the specific organisation and not from all organisations that the user might belong

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /users/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Users
GET /users

Retrieve a list of users based on search criteria (e.g. all active users)

Request parameters

search_value
string optional

The value of the search (case insensitive) across Full Name (first + last name), Email Address, Phone Number

Example:
John Doe
first_name
string optional

The user first name

Example:
John
last_name
string optional

The user last name

Example:
Doe
email_address
string optional

The user email address

Example:
johndoe@crm.com
pending_invitation
boolean optional

Defines wchich users should be returned (false: retrieve all users that have accepted their invitation, true: retrieve users that have pendingi invitation, null: retrieve all users)

Allow empty value: true
Example:
false
user_roles
array of string optional

Filter users based on user roles

Collection format: csv
Unique items: YES
teams
array of string optional

Filter users based on teams

Collection format: csv
Unique items: YES
is_locked
boolean optional

Defines which users will be retrieved based on whether they are locked due to incorrect password validations or not

Example:
true
is_active
boolean optional

Defines which users will be retrieved based on their status

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
preferred_language
string

The language preferred by the user for communication

Example:
GR
software_language
string

The language preferred by the user for software translation

Example:
EN
is_active
boolean

The user’ status

Example:
true
invitation_date
integer epoch

The date when the user was invited

Example:
1581009106
tfa_enabled
boolean

Defines whether two-factor authentication is enabled or not

Example:
true
lock_expiration
integer epoch

Defines when the user lockout period will end (applicable if the user is locked out due to reaching the maximum invalid password attempts)

Example:
1617094607
role
Object

Information about the user roles

id
string GUID

The user role identifier

Example:
1a917631-b103-c47d-283f-53cc50ba1e2b
name
string

The user role name

Example:
Owner
contact_info
Array

Information about the user’s contact details

Object
id
string GUID

The user’s contact info identifier

Example:
AUR1E31269B76D7A65ACCE45B2E68DFD
name
string

The contact info name

Example:
Work
type
string

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string

The value of the contact info

Example:
johndoe@crm.com
is_identity
string

Defines whether the contact info is used as an user’s identidy

Example:
true
identity
Array

Information about the user’s identities

Object
id
string GUID

The user identity

Example:
CAD1QQ1269B76D7A65ACCE45B2E68DFD
provider
string

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string

the identity’s challenge

Example:
johndoe@crm.com
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
last_login
integer epoch

The timestamp of the user’s last login

Example:
1663072342
last_deactivation
integer epoch

The timestamp of the user’s last deactivation

Example:
1663072342
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /users HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "first_name": "John",
            "last_name": "Doe",
            "is_active": true,
            "role": {
                "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
                "name": "Owner"
            },
            "contact_info": [
                {
                    "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
                    "type": "EMAIL",
                    "value": "johndoe@crm.com",
                    "is_identity": "true"
                }
            ],
            "identity": [
                {
                    "id": "CAD1QQ1269B76D7A65ACCE45B2E68DFD",
                    "provider": "EMAIL",
                    "identity_challenge": "johndoe@crm.com"
                }
            ],
            "creatives": [
                {
                    "id": "CA123456789AQWSXZAQWS1236547896541",
                    "type": "MARKETING",
                    "width": 2159,
                    "height": 3075,
                    "format": "jpg",
                    "url": "https://assets.crm.com/image/offer.jpg",
                    "public_id": "crm-com/image",
                    "media": [
                        {
                            "width": 200,
                            "height": 300,
                            "url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
                        }
                    ]
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get User
GET /users/{id}

Get details for a single user

Path variables

id
string GUID required

The user (identifer) that will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
preferred_language
string

The language preferred by the user for communication

Example:
EN
software_language
string

The language preferred by the user for software translation

Example:
GR
role
Object

Information about the user roles

id
string GUID

The user role identifier

Example:
1a917631-b103-c47d-283f-53cc50ba1e2b
name
string

The user role name

Example:
Owner
contact_info
Array

Information about the user’s contact details

Object
id
string GUID

The contact info identifier

Example:
AUR1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the contact info

Example:
Mobile
type
string

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string

The value of the contact info

Example:
johndoe@crm.com
is_identity
boolean

Defines whether the contact info is used as an user’s identidy

Example:
true
identity
Array

Information about the user’s identities

Object
id
string GUID

The user identity

Example:
CAD1QQ1269B76D7A65ACCE45B2E68DFD
provider
string

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string

The identity’s challenge

Example:
johndoe@crm.com
teams
Array

The teams that the user is part of

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Marketing
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
last_login
integer epoch

The timestamp of the user’s last login

Example:
1663072342
last_deactivation
integer epoch

The timestamp of the user’s last deactivation

Example:
1663072342
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /users/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "first_name": "John",
    "last_name": "Doe",
    "preferred_language": "EN",
    "role": {
        "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
        "name": "Rewards Manager"
    },
    "contact_info": [
        {
            "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Work",
            "type": "EMAIL",
            "value": "johndoe@crm.com",
            "is_identity": "true"
        }
    ],
    "identity": [
        {
            "id": "CAD1QQ1269B76D7A65ACCE45B2E68DFD",
            "provider": "EMAIL",
            "identity_challenge": "johndoe@crm.com"
        }
    ],
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "type": "PROFILEIMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/offer.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
                }
            ]
        }
    ]
}
Get User - My Profile
GET /users/{id}/my_profile

Get details for the signed-in user

Path variables

id
string GUID required

The (signed-in) user (identifer) that will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
first_name
string

The user’s first name

Example:
John
last_name
string

The user’s last name

Example:
Doe
preferred_language
string

The language preferred by the user for communication

Example:
EN
software_language
string

The language preferred by the user for software translation

Example:
GR
role
Object

Information about the user roles

id
string GUID

The user role identifier

Example:
1a917631-b103-c47d-283f-53cc50ba1e2b
name
string

The user role name

Example:
Owner
contact_info
Array

Information about the user’s contact details

Object
id
string GUID

The contact info identifier

Example:
AUR1E31269B76D7A65ACCE45B2E68DFD
name
string

The name of the contact info

Example:
Mobile
type
string

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string

The value of the contact info

Example:
johndoe@crm.com
is_identity
boolean

Defines whether the contact info is used as an user’s identidy

Example:
true
identity
Array

Information about the user’s identities

Object
id
string GUID

The user identity

Example:
CAD1QQ1269B76D7A65ACCE45B2E68DFD
provider
string

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string

The identity’s challenge

Example:
johndoe@crm.com
teams
Array

The teams that the user is part of

Object
id
string GUID

The organisation identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The organisation name

Example:
Marketing
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /users/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "first_name": "John",
    "last_name": "Doe",
    "preferred_language": "EN",
    "role": {
        "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
        "name": "Rewards Manager"
    },
    "contact_info": [
        {
            "id": "AUR1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Work",
            "type": "EMAIL",
            "value": "johndoe@crm.com",
            "is_identity": "true"
        }
    ],
    "identity": [
        {
            "id": "CAD1QQ1269B76D7A65ACCE45B2E68DFD",
            "provider": "EMAIL",
            "identity_challenge": "johndoe@crm.com"
        }
    ],
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "type": "PROFILEIMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/offer.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/offer.jpg"
                }
            ]
        }
    ]
}
Get User Organisations
GET /users/organisations

Retrieve a list of organisations that a user is a member to

Request parameters

username
string required

The user’s username that will be used for retrieving the organisations that such user is a member to

Example:
johndoe@crm.com

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The organisation identifier

Example:
a15947aa-3596-29d2-9a99-c9c3e5114904
name
string

The organisation name

Example:
CRM.COM
login_method
string

The organisation supported login method

Enumeration:
USERNAME_PASSWORD
OIDC
public_api_key
string

The public API Key for the organisation

Example:
bb511dbf-cdb0-b446-c329-01bb12de4126
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/users/organisations?username=johndoe@crm.com HTTP/1.1

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "b780f4d2-59c1-e3be-cbe6-247df4117793",
        "name": "CRM.COM",
        "login_method": "USERNAME_PASSWORD",
        "public_api_key": "11f4b2bb-65d9-46b5-9ca3-b726778f651f"
    }
]
Activate User
POST /users/{id}/activate

Activate a specific user

Path variables

id
string GUID required

The user (identifer) that will be activates

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CK1234567890123456789012345678/activate HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Deactivate User
POST /users/{id}/deactivate

Deactivate a specific user

Path variables

id
string GUID required

The user (identifer) that will be deactivated

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CK1234567890123456789012345678/deactivate HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Resend User Invitation
POST /users/{id}/invite_resend

Resend a user invitation

Path variables

id
string GUID required

The user (identifer) that invitation will be send again

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CAD1E31269B76D7A65ACCE45B2E68DFD/invite_resend HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Resend User Verification
POST /users/verify_resend

Resend a user verification

Request headers

api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
email
string

The email that was used during registration and verification should be resend (if matched)

Example:
john@crm.com

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/verify_resend HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "email": "john@crm.com"
}

HTTP/1.1 200 OK 
Revoke User Invitation
DELETE /users/{id}/invite_revoke

Resend a user invitation

Path variables

id
string GUID required

The user (identifer) that invitation will be revoked

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /users/CAD1E31269B76D7A65ACCE45B2E68DFD/invite_revoke HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
User Media Groups
POST /users/{id}/media_groups

Link a user with one or many media groups

Path variables

id
string GUID required

The user (identifer) that media groups will be updated

Example:
sdfsfsdf-32-fwef-wef-wefwef23

Notes

MEDIA UPLOAD

Uploading media for a user requires the execution of the following APIs

  1. Create new Media Group
  2. Create User Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/sdfsfsdf-32-fwef-wef-wefwef23/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK 
Actions on Users
POST /users/{id}/actions

Perform an action on a single user

Path variables

id
string GUID required

The user (identifer) that an action will be applied

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
actions
string required

The action that will be applied on the user

Enumeration:
CANCEL_LOCK

Cancel the lockout that is applied on user due to invalid authentication (reaching the max auth attemps with no success)

Responses

200 200

OK

Body
Object
id
string GUID

The user identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/CK1234567890123456789012345678/actions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "actions": "CANCEL_LOCK"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
User Contact Info
POST /users/{id}/contactinfo
PUT /users/{id}/contactinfo/{contactinfo_id}
DELETE /users/{id}/contactinfo/{contactinfo_id}
Add Contact Info
POST /users/{id}/contactinfo

Add contact info to a specific user

Path variables

id
string GUID required

The user (identifer) whose contact info will be added

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The contact info name

Example:
Work
type
string required

The type of the contact information

Enumeration:
PHONE
EMAIL
EXTENSION
value
string required

The contact info value

Example:
jd@crm.com

Responses

200 200

OK

Body
Object
id
string GUID

The user contact info identifier

Example:
AK1234567890123456789012345678
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CK1234567890123456789012345678/contactinfo HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Work",
    "type": "EMAIL",
    "value": "jd@crm.com"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "AK1234567890123456789012345678"
}
Update Contact Info
PUT /users/{id}/contactinfo/{contactinfo_id}

Update existing contact info of a specific user

Path variables

id
string GUID required

The user (identifer) whose contact info will be update

Example:
CK1234567890123456789012345678
contactinfo_id
string GUID required

The contact info (identifer) that will be updated

Example:
AK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The contact info name

Example:
Work
value
string nullable

The contact info value

Example:
jd@crm.com

Responses

200 200

OK

Body
Object
id
string GUID

The user contact info identifier

Example:
AK1234567890123456789012345678
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /users/CK1234567890123456789012345678/contactinfo/AK1234567890123456789012345678 HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Work",
    "value": "jd@crm.com"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "AK1234567890123456789012345678"
}
Delete Contact Info
DELETE /users/{id}/contactinfo/{contactinfo_id}

Delete existing contact info of a specific user

Path variables

id
string GUID required

The user (identifer) whose contact info will be deleted

Example:
CK1234567890123456789012345678
contactinfo_id
string GUID required

The contact info (identifer) that will be deleted

Example:
AK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /users/CK1234567890123456789012345678/contactinfo/AK1234567890123456789012345678 HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
User Identities
POST /users/{id}/identities
PUT /users/{id}/identities/{identity_id}
DELETE /users/{id}/identities/{identity_id}
Create User Identity
POST /users/{id}/identities

Create an identity for a specific user

Path variables

id
string GUID required

The user (identifer) whose identity will be created

Example:
CK1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
provider
string required

The provider of the identity

Enumeration:
EMAIL
PHONE
identity_challenge
string required

The user’s challenge

Example:
johndoe@crm.com
identity_value
string nullable

The user’s value (applicable only when provider is EMAIL based)

Example:
1234

Responses

200 200

OK

Body
Object
id
string GUID

The user identity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CK1234567890123456789012345678/identities/ID1234567890123456789012345678 HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "identity_challenge": "johndoe@crm.com",
    "identity_value": "1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update User Identity
PUT /users/{id}/identities/{identity_id}

Update an identity for a specific user

Path variables

id
string GUID required

The user (identifer) whose identity will be updated

Example:
CK1234567890123456789012345678
identity_id
string GUID required

The identity (identifer) that will be updated

Example:
ID1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
identity_challenge
string required

The user’s identity challenge

Example:
johndoe@crm.com
identity_value
string required

The user’s identity value (applicable only when identity is EMAIL based)

Example:
1234
current_value
string required nullable

The user’s identity previous value (applicable only when identity is EMAIL based)

Example:
4321

Responses

200 200

OK

Body
Object
id
string GUID

The user identity identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /users/CK1234567890123456789012345678/identities/ID1234567890123456789012345678 HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "identity_challenge": "johndoe@crm.com",
    "identity_value": "1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete User Identity
DELETE /users/{id}/identities/{identity_id}

Delete an identity for a specific user

Path variables

id
string GUID required

The user (identifer) whose identity will be deleted

Example:
CK1234567890123456789012345678
identity_id
string GUID required

The identity (identifer) that will be deleted

Example:
ID1234567890123456789012345678

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /users/CK1234567890123456789012345678/identities/ID1234567890123456789012345678 HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Two Factor Authentication
POST /users/{id}/two_factor_methods
DELETE /users/{id}/two_factor_methods/{tfm_id}
GET /users/{id}/two_factor_methods
PUT /users/{id}/two_factor_methods/{tfm_id}/actions
POST /users/{id}/two_factor_methods/backup
Create Two Factor Auth Method
POST /users/{id}/two_factor_methods

Create a 2FA method for a specific user

Path variables

id
string GUID required

The user (identifier) that two-factor method will be created

Example:
43459841-5a83-1cd1-92c1-1b9238c0603a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
method
string required

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string required

The two-factor authentication value

Example:
john@crm.com

Responses

200 OK
Body
Object
id
string GUID

The two-factor authentication method identifier

Example:
bd3b7775-8d33-96d1-2788-fc48ad9fa70c
totp
Object

The two-factor authentication time-based one-time password (TOTP) details

url
string

The TOTP URL that will be used for the QR code

Example:
https://crm.com
value
string

The TOTP key that can be used for manual registration on an authenticator app

Example:
123456qwerty
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Delete Two Factor Auth Method
DELETE /users/{id}/two_factor_methods/{tfm_id}

Delete a user’s existing two-factor authentication method

Path variables

id
string GUID required

The user (identifier) whose two-factor authentication method will be deleted

Example:
43459841-5a83-1cd1-92c1-1b9238c0603a
tfm_id
string GUID required

The two-factor authentication method (identifier) that will be deleted

Example:
30213192-3bd2-868e-128e-b93495526e8f

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

204 No Content

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/users/43459841-5a83-1cd1-92c1-1b9238c0603a/two_factor_methods/30213192-3bd2-868e-128e-b93495526e8f HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 204 No Content 
List Two Factor Auth Methods
GET /users/{id}/two_factor_methods

Retrieve a list of a user’s two-factor authentication methods based on search criteria (e.g. all methods)

Path variables

id
string GUID required

The user (identifier) whose two-factor authentication methods will be retrieved

Example:
43459841-5a83-1cd1-92c1-1b9238c0603a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 OK

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The two-factor authentication method identifier

Example:
e44d7b18-c4b1-c7d7-30ef-7e5a01c77cf0
method
string

The two-factor method

Enumeration:
EMAIL
PHONE
TOTP
value
string

The two-factor authentication obfuscated value (applicable only for email and phone based methods)

Example:
j_*****@crm.com
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/users/43459841-5a83-1cd1-92c1-1b9238c0603a/two_factor_methods HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "e44d7b18-c4b1-c7d7-30ef-7e5a01c77cf0",
            "method": "EMAIL",
            "value": "j_*****@crm.com"
        }
    ]
}
Two Factor Auth Method Actions
PUT /users/{id}/two_factor_methods/{tfm_id}/actions

Perform actions on a user’s newly added two-factor authentication method

Path variables

id
string GUID required

The user (identifier) whose two-factor authentication method will be updated

Example:
43459841-5a83-1cd1-92c1-1b9238c0603a
tfm_id
string GUID required

The two-factor authentication method that actions will be applied on

Example:
30213192-3bd2-868e-128e-b93495526e8f

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Request body

Object
action
string

The action that will be applied on the two-factor authentication method

Enumeration:
VERIFY
code
string

The 6-digit verification code (required for VERIFY action)

Example:
135792

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The two-factor authentication method identifier

Example:
0bb44610-f77c-85e0-f8a1-d35da22f5c78
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/users/43459841-5a83-1cd1-92c1-1b9238c0603a/two_factor_methods/30213192-3bd2-868e-128e-b93495526e8f/actions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "action": "VERIFY",
    "code": "135792"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0bb44610-f77c-85e0-f8a1-d35da22f5c78"
}
Generate User Two-Factor Authentication Backup Code
POST /users/{id}/two_factor_methods/backup

Generate a new back-up code (unique 24-alphanumeric character code) as part of a user’s two-factor authentication method

Path variables

id
string GUID required

The user (identifier) for which a two-factor authentication backup code will be generated

Example:
43459841-5a83-1cd1-92c1-1b9238c0603a

Notes

BACK-UP CODE

Back-up code can be used for authentication purposes (sign-in) when user forgets all two-factor authentication methods does not have access to them

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

Responses

200 OK

The request has succeeded

Body
Object
backup_code
string

The two-factor authentication back-up code

Example:
ybkc-efxv-rggd-qtdv-xckg
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/43459841-5a83-1cd1-92c1-1b9238c0603a/two_factor_methods/backup HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "backup_code": "ybkc-efxv-rggd-qtdv-xckg"
}
System Monitor

The following group will detail the API’s required in order to monitor the events and logs taking place in the system.

GET /event_logs
GET /event_logs/{id}
GET /api_logs
GET /api_logs/{id}
List Events
GET /event_logs

Returns a list of Events logged in MongoDB

Request parameters

search_value
string optional

Search for an event using keywords relating to the event description or event name.

Example:
Register
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
contact_id
string optional

Retrieve events submitted by a specific contact

Example:
B76D7A65ACCE45B2E68DFDCAD1E31269
entity
string optional

Retrieve events for a specific entity

Enumeration:
ACTIVITY
AWARD_REWARD_TRANSACTION
CONTACT
CREDIT_NOTE
INVOICE
ORDER
PASS
PAYMENT
PAYOUT
PURCHASE
REFERRAL
REFUND
REWARD_OFFER
SERVICE_REQUEST
SPEND_REWARD_TRANSACTION
SUBSCRIPTION
USER
api_log_id
string optional

Retrieve a single event using the unique API log id

Example:
529983f1-1d5d-4e88-83b5-ba30715a809c
submitted_date
string optional

Filter events based on date submitted

Enumeration:
submitted_date[gt]

Returns results where the submitted date is greater than this value

submitted_date[gte]

Returns results where the submitted date is greater than or equal to this value

submitted_date[lt]

Returns results where the submitted date is less than this value

submitted_date[lte]

Returns results where the submitted date is less then or equal to this value

submited_by_user_id
string optional

Filter events based on unique id of the system user

Example:
f9d3a05b-0d95-44fa-bc64-3b0aa434470b
entity_id
string GUID optional

Filter based on entity (identifier) associated to such event

Example:
c35cbdda-1bc2-ff81-50bb-098058c714ee

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array

Details relating to the event.

Object
id
string GUID

The event identifier

Example:
evnt_IGD78345hjhDFHD76t883hnfh
submitted_date
integer epoch

The date&time that the event was created.

Example:
1625472619
description
string
entity
string
api_log_id
string
submitted_by_user_name
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/events HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "evnt_IGD78345hjhDFHD76t883hnfh",
            "source": "/organisations/ba7944ab-53ef-4425-ac7c-faaf2e33a4a1/switch",
            "status": "200",
            "submitted_date": 1625472619,
            "method": "POST",
            "reason_phrase": "OK"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Event
GET /event_logs/{id}

Returns an Event logged in Mongo DW

Path variables

id
string GUID required

The event (identifier) to retrieve the details

Example:
407eebd4-dd56-f522-60f5-929dfe3f58df

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
api_log_id
string
description
string
entity
string
entity_data
string
entity_id
string
id
string
submitted_by_user_id
string
submitted_by_user_name
string
submitted_date
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List API Logs
GET /api_logs

Retrieves all API logs.

Request parameters

search_value
string optional

search by entity_id and source

source
string optional

search by source

entity_id
string GUID optional

Filter based on entity (identifier)

Example:
b2ce56e8-9fd1-06cb-e8c0-6e7e73fea317
method
string optional
Enumeration:
POST
PUT
DELETE
statuses
array of string optional

List of statuses in order to search logs based on multiple statuses

Collection format: csv
submitted_date
string optional

Filter API logs based on date submitted

Enumeration:
submitted_date[gt]

Returns results where the submitted date is greater than this value

submitted_date[gte]

Returns results where the submitted date is greater than or equal to this value

submitted_date[lt]

Returns results where the submitted date is less than this value

submitted_date[lte]

Returns results where the submitted date is less then or equal to this value

submited_by_user_id
string optional

Filter API log based on unique id of the system user

Example:
f9d3a05b-0d95-44fa-bc64-3b0aa434470b
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The API log identifier

Example:
b6c1c158-7ef8-4f1a-82d1-060dcc9e3da2
method
string

The API method

Enumeration:
PUT
POST
DELETE
source
string

The API source

Example:
/organisations/ba7944ab-53ef-4425-ac7c-faaf2e33a4a1/switch"
submitted_date
string
status
integer

The API log status

reason_phrase
string

The status info

Example:
400 Bad Request
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/api_logs HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "b6c1c158-7ef8-4f1a-82d1-060dcc9e3da2",
            "status": 1,
            "method": "DELETE",
            "source": "/organisations/ba7944ab-53ef-4425-ac7c-faaf2e33a4a1/switch\"",
            "reason_phrase": "OK",
            "submitted_date": ""
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get API Log
GET /api_logs/{id}

Retrieves details regarding to the specific log

Path variables

id
string GUID required

The log (identifier) to be retrieved

Example:
6ccff6a9-b0fe-a6f5-878b-b982d293d3ca

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
name
string
Example:
updateProductTypes
method
string
Enumeration:
PUT
POST
DELETE
api_version
string
ip_address
string
source
string

The API (URL) endpoint

Example:
/product_types/9EAA2884B6D04DD89F324A26D63944C9
request
string
Example:
"composition_method\":\"FLAT\",\"name\":\"Consumables\",\"description\":null,\"negative_balance_allowed\":false,\"display_name\":\"\",\"is_modifier\":false,\"is_stockable\":false,\"variant_attributes\":[]}
status
integer
reason_phrase
string

The status info

Example:
400 Bad Request
response
string
Example:
{\"id\":\"9EAA2884B6D04DD89F324A26D63944C9\"}", "id":"849a07f0-f180-47ef-9c4a-89a67306ebfe", "ip_address":"172.30.182.233", "api_version":"V1", "reason_phrase":"OK", "submitted_date":1630312452 ":[]}
submitted_date
string
submitted_by_user_id
string
submitted_by_user_name
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/api_logs/42f75e3f-5337-2358-5ec0-9025992c9e3b HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "updateProductTypes",
    "source": "/product_types/9EAA2884B6D04DD89F324A26D63944C9",
    "status": 1,
    "method": "DEL",
    "request": "\"composition_method\\\":\\\"FLAT\\\",\\\"name\\\":\\\"Consumables\\\",\\\"description\\\":null,\\\"negative_balance_allowed\\\":false,\\\"display_name\\\":\\\"\\\",\\\"is_modifier\\\":false,\\\"is_stockable\\\":false,\\\"variant_attributes\\\":[]}",
    "response": "{\\\"id\\\":\\\"9EAA2884B6D04DD89F324A26D63944C9\\\"}\",    \"id\":\"849a07f0-f180-47ef-9c4a-89a67306ebfe\",    \"ip_address\":\"172.30.182.233\",    \"api_version\":\"V1\",    \"reason_phrase\":\"OK\",    \"submitted_date\":1630312452 \":[]}"
}
Settings - Configuration
Accounts
GET /accounting_periods
GET /account_generic_settings
PUT /account_generic_settings
List Accounting Periods
GET /accounting_periods

Retrieve the Accounting Periods

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Array
Object
accounting_period_id
string GUID

The ID of the accounting period

Example:
4AD9C84FA60F9FE407140E20F707726A
number
string

The number of the accounting period

Example:
102019
name
string

The name of the accounting period

Example:
OCTOBER2019
from_date
string epoch

The starting date of the accounting period

Example:
1583764050
to_date
string epoch

The ending date of the accounting period

Example:
1583764050
life_cycle_state
string

The life cycle state of the accounting period

Enumeration:
OPEN
CLOSED
closed_date
integer

The actual date that the period was closed

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /accounting_periods HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "accounting_period_id": "4AD9C84FA60F9FE407140E20F707726A",
        "number": "102019",
        "name": "OCTOBER2019",
        "from_date": "1583764050",
        "to_date": "1583764050",
        "life_cycle_state": "OPEN",
        "closed_date": "1583764050"
    }
]
Get Account Generic Settings
GET /account_generic_settings

Get the generic account settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
name_display_settings
string
Example:
ACCOUNT_CONTACT_NAME
allocation_settings
string
Example:
FIFO_AGAINST_ITEM
accounting_period_settings
Object
close_months_before
integer
Example:
1
credit_terms_settings
Object
credit_limit
number

The default Credit Limit that a contact will be assigned when creating a new Account. Defines in the business’s base currency

Example:
9.99
payment_terms
Object
id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
type
string
Enumeration:
DUE_IMMEDIATELLY
NET_7
NET_30
NET_60
CUSTOM
Default:
DUE_IMMEDIATELLY
Example:
NET_7
label
string
Example:
Net 7
net_term_days
integer

Number of dayswithin which an Invoice is due to be paid

Example:
7
additional_rules
Array
Object
credit_limit
number
Example:
8.99
payment_terms
Object
id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
type
string
Example:
DUE_IMMEDIATELLY
label
string
Example:
Due Immediatelly
net_term_days
integer
account_classifications
Array
Object
id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
name
string
Example:
VIP
numbering_schemes
Array
Object
entity
string
Example:
INVOICE
prefix
string
starting_number
string
number_of_digits
integer
Example:
1
last_number
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/account_generic_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name_display_settings": "ACCOUNT_CONTACT_NAME",
    "allocation_settings": "FIFO_AGAINST_ITEM", 
    "accounting_period_settings": {
        "close_months_before": 1
    },
    "credit_terms_settings": {
        "credit_limit": 9.99,
        "payment_terms": {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "type": "NET_7",
            "label": "Net 7",
            "net_term_days": 7
        },
        "additional_rules": [
            {
                "credit_limit": 8.99,
                "payment_terms": {
                    "id": "4AD9C84FA60F9FE407140E20F707726A",
                    "type": "DUE_IMMEDIATELLY",
                    "label": "Due Immediatelly",
                    "net_term_days": 1
                },
                "account_classifications": [
                    {
                        "id": "4AD9C84FA60F9FE407140E20F707726A",
                        "name": "VIP"
                    }
                ]
            }
        ]
    },
    "numbering_schemes": [
        {
            "entity": "INVOICE",
            "prefix": "",
            "starting_number": "",
            "number_of_digits": 1,
            "last_number": ""
        }
    ]
}
Update Account Generic Settings
PUT /account_generic_settings

Update the generic account settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name_display_settings
string
Example:
ACCOUNT_CONTACT_NAME
allocation_settings
string
Example:
FIFO_AGAINST_ITEM
accounting_period_settings
Object
close_months_before
integer
Example:
3
credit_terms_settings
Object
credit_limit
number
Example:
9.99
payment_terms_id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
additional_rules
Array
Object
credit_limit
number
Example:
8.99
payment_terms_id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
account_classifications
Array
Object
id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
name
string
Example:
VIP
numbering_schemes
Array
Object
entity
string
Example:
INVOICE
prefix
string
number_of_digits
integer
Example:
5
starting_number
string
Example:
00001

Responses

200 200

Successful Request

Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/account_generic_settings HTTP/1.1 

Content-Type: application/json

{
    "name_display_settings": "ACCOUNT_CONTACT_NAME",
    "allocation_settings": "FIFO_AGAINST_ITEM",
    "accounting_period_settings": {
        "close_months_before": 3
    },
    "credit_terms_settings": {
        "credit_limit": 9.99,
        "payment_terms_id": "4AD9C84FA60F9FE407140E20F707726A",
        "additional_rules": [
            {
                "credit_limit": 8.99,
                "payment_terms_id": "4AD9C84FA60F9FE407140E20F707726A",
                "account_classifications": [
                    {
                        "id": "4AD9C84FA60F9FE407140E20F707726A",
                        "name": "VIP"
                    }
                ]
            }
        ]
    },
    "numbering_schemes": [
        {
            "entity": "INVOICE",
            "prefix": "",
            "number_of_digits": 5,
            "starting_number": "00001"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Account Classifications
POST /account_classifications
PUT /account_classifications/{id}
DELETE /account_classification/{id}
GET /account_classifications
Create Account Classifications
POST /account_classifications

Create the account classifications

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the classification to be created

Example:
VIP
is_default
boolean

Determines whether it’s the default classification

Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the classification

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Account Classification
PUT /account_classifications/{id}

Update a specific account classification

Path variables

id
string GUID required

The account classification identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
classification_name
string

The name of the classification

Example:
VIP
is_default
boolean

Determines whether it’s the default classification

Example:
true

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the account classification

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Delete Account Classification
DELETE /account_classification/{id}

Delete a specific account classification

Path variables

id
string GUID required

The account classification identifier that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Account Classifications
GET /account_classifications

List all the available account classifications

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC
name
string optional

The name of the account classification

Example:
VIP

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
name
string
Example:
Normal
id
string
Example:
7b3a5787-1f0f-4062-b373-df2ecf943658
is_default
boolean
Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/account_classifications HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "Normal",
            "id": "7b3a5787-1f0f-4062-b373-df2ecf943658",
            "is_default": true
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Payment Terms
POST /payment_terms
PUT /payment_terms/{id}
GET /payment_terms
DELETE /payment_terms/{id}
Create Payment Terms
POST /payment_terms

Creates a new Payment Term

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
net_term_days
integer required

The number of days in which the invoice will be due

Example:
180
is_default
boolean

Determines whether it’s the default payment term

Default:
false
Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the payment term

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/payment_terms HTTP/1.1 

Content-Type: application/json

{
    "net_term_days": 180,
    "is_default": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update Payment Terms
PUT /payment_terms/{id}

Updates an existing Payment Term

Path variables

id
string required

The unique identifier of the Payment Term to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
net_term_days
integer required

The number of days in which the invoice will be due

Example:
180
is_default
boolean

Determines whether it’s the default payment term

Default:
false
Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the payment term

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/payment_terms/{id} HTTP/1.1 

Content-Type: application/json

{
    "net_term_days": 180,
    "is_default": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
List Payment Terms
GET /payment_terms

List all the available Payment Terms

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC
value
string optional

The name of the Payment Term

Example:
Net 7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string
Example:
4AD9C84FA60F9FE407140E20F707726A
name
string
Example:
Net 7
net_term_days
integer
Example:
7
is_default
string
Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/payment_terms HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Net 7",
            "net_term_days": 7,
            "is_default": "true"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Delete Payment Terms
DELETE /payment_terms/{id}

Delete a specific payment term

Path variables

id
string GUID required

The payment terms identifier that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/payment_terms/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

HTTP/1.1 204 No Content 
Activities
Activity Types
POST /activity_types
PUT /activity_types/{id}
DELETE /activity_types/{id}
GET /activity_types
GET /activity_types/{id}
Create Activity Type
POST /activity_types

Create an activity type.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A unique name for the type

Example:
Installations
description
string

The description of the type.

Example:
A customer requires an installation of some sorts.
color
string

The unique colour code relating to the type.

Example:
FAC9990
Examples

Responses

201 Created
Body
Object
id
string

The unique identifier of the newly created type

Example:
V349C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/types HTTP/1.1 

Content-Type: application/json

{
    "name": "Installations",
    "description": "A customer requires an installation of some sorts.",
    "color": "FAC9990",
    "owner": [
        {
            "user id": "4KHSKUFGKNS8369874KJGJKS",
            "name": "John Smith"
        }
    ]
}
Update Activity Type
PUT /activity_types/{id}

Update an activity type.

Path variables

id
string GUID required

The GUID of the activity type

Example:
JHGSKJGSE7686487643HJGFSG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A unique name for the type

Example:
Installations
state
string

The state of the type.

Example:
Active
description
string

The description of the type.

Example:
A customer requires an installation of some sorts.
color
string

The unique colour code relating to the type.

Example:
FAC9990
Examples

Responses

201 Created
Body
Object
id
string

The unique identifier of the newly created type

Example:
V349C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/types/JHGSKJGSE7686487643HJGFSG HTTP/1.1 

Content-Type: application/json

{
    "name": "Installations",
    "state": "Active",
    "description": "A customer requires an installation of some sorts.",
    "color": "FAC9990",
    "resources": [
        {
            "user id": "4KHSKUFGKNS8369874KJGJKS",
            "name": "John Smith"
        }
    ]
}
Delete Type
DELETE /activity_types/{id}

Delete a type.

Path variables

id
string required

The GUID of the type to be deleted

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/queues/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 
List Types
GET /activity_types

Retrieve all details pertaining to activity types.

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for a queue using its name

state
string optional

The state of the activity

Enumeration:
ACTIVE
INACTIVE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The GUID of the type

Example:
74D9C84FA60F9FE407140E20F707726A
name
string

The name of the queue

Example:
Billing Issues
state
string

The life cycle state of the queue

Example:
Active
description
string

The decsription of the type.

Example:
The user requires installation of some type.
color
string

The unique colour code that has been assigned to the queue type.

Example:
F56CSD
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/types HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "74D9C84FA60F9FE407140E20F707726A",
            "name": "Billing Issues",
            "state": "Active",
            "number_of_users": 5,
            "description": "The user requires installation of some type.",
            "color": "F56CSD"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Type
GET /activity_types/{id}

Retrieve a types details.

Path variables

id
string GUID required

The activity type identifier that will details will be retrieved

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The GUID of the retrieved type.

name
string

The types’s name

Example:
Installation
state
string

The life cycle state of the type

Example:
Active
description
string

The description of the type.

Example:
The user requires an installation of some sorts.
color
string

The unique color code assigned to the type.

Example:
TRD45F
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/activity_types/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "name": "Installation",
    "state": "Active",
    "description": "The user requires an installation of some sorts.",
    "color": "TRD45F",
    "resources": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "John Snow"
        }
    ]
}
Business Network
PUT /business_network_settings
GET /business_network_settings
PUT /community_commerce
GET /community_commerce
GET /settlement_transactions
Set Business Network Settings
PUT /business_network_settings

Update the generic business network settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
model
Array required nullable

Defines which organisation types will consist the business network

Examples:
[
    "MERCHANT_VENUE"
]
[
    "SERVICE_PROVIDER_POINT"
]
string
Enumeration:
MERCHANT_VENUE
SERVICE_PROVIDER_POINT

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/business_network_settings HTTP/1.1 

Content-Type: application/json

{
    "model": [
        "SERVICE_PROVIDERS",
        "SERVICE_POINTS"
    ]
}

HTTP/1.1 200 OK 
Get Business Network Settings
GET /business_network_settings

Retrieve business network generic settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
model
Array

Defines which organisation types will consist the business network

Examples:
[
    "MERCHANT_VENUE"
]
[
    "SERVICE_PROVDER_POINT"
]
string
Enumeration:
MERCHANT_VENUE
SERVICE_PROVIDER_POINT
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/business_network_settings HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "model": [
        "SERVICE_PROVIDERS",
        "SERVICE_POINTS"
    ]
}
Set Community Commerce
PUT /community_commerce

Update the community commerce settings (e.g. B2B Settlement)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
settlement_settings
Object nullable

Details about settlement settings (required if settlement is enabled)

enable_settlement
boolean required

Defines whether settlement is enabled or not

Example:
false
settlement_evaluation
string nullable

Defines when settlement will take place

Enumeration:
REAL_TIME
HOURLY
DAILY
WEEKLY
MONTHLY
Default:
DAILY
frequency
string nullable

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
settlement_fees
Object nullable

Details about the settlement fee(s) that will be applied on award and/or spend transactions (applicable only if settlement is enabled)

enable_settlement_fees
boolean required

Defines whether settlement fees will be applied or not

Example:
true
fee_type
string required

Defines whether the related type will be amount or percentage based

Enumeration:
AMOUNT
PERCENTAGE
default_award_fee
number required

Defines the default fee on award that will be applied on all organisations (merchants/service providers)

Example:
1.99
default_spend-fee
number required

Defines the default fee on spend that will be applied on all organisations (merchants/service providers)

Example:
2.91
explicit_fees
Array nullable

Defines the fees that will be applied explicitly on specific organisations (merchants/service providers)

Object
entity_type
string required

Defines the entity type that fees will be explicitly applied

Enumeration:
ORGANISATION
entity_id
string GUID required

Defines the entity identifier that fees will be explicitly applied

Example:
3a4ff705-356d-16e4-d5f7-dd5e7c3c29d5
award_fee
number nullable

The explicit award fee

Example:
5.91
spend_fee
number nullable

The explicit spend fee

Example:
1.99
settlement_rules
Object nullable

Defines the settlement rules that will be applied during settlement (e.g. financial transaction types)

financial_transactions
Object nullable

Defines the financial transaction types that will be used when posting a payment/payout during settlement

payment_type_id
string GUID nullable

The payment type identifier that will be used. If not specified, then the default type will be used

Example:
cf916e07-0f19-4640-a800-3fc9b3ba509c
payout_type_id
string GUID nullable

The payout type identifier that will be used. If not specified, then the default type will be used

Example:
4ff4cefb-05c7-2db6-19f7-917e6770219b
amount_allowance
Object nullable

Defines the min/max amount that can be settled against an organisation account

min_amount
number nullable

The min amount that can be settled against an organisation account

Example:
99.99
max_amount
number nullable

The max amount that can be settled against an organisation account

Example:
999.99

Responses

200 200

Successful Request

Body
Object
id
string GUID

The organisation identifier

Example:
a331211c-7a48-c107-096e-870a574f0e85
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/community_commerce HTTP/1.1 

Content-Type: application/json

{
    "settlement_settings": {
        "enable_settlement": "false",
        "settlement_evaluation": "DAILY",
        "frequency": "0 0 12 * * ?"
    },
    "settlement_fees": {
        "enable_settlement_fees": "true",
        "fee_type": "AMOUNT",
        "default_award_fee": 1.99,
        "default_spend-fee": 2.91,
        "explicit_fees": [
            {
                "entity_type": "ORGANISATION",
                "entity_id": "3a4ff705-356d-16e4-d5f7-dd5e7c3c29d5",
                "award_fee": 5.91,
                "spend_fee": 1.99
            }
        ]
    },
    "settlement_rules": {
        "financial_transactions": {
            "payment_type_id": "cf916e07-0f19-4640-a800-3fc9b3ba509c",
            "payout_type_id": "4ff4cefb-05c7-2db6-19f7-917e6770219b"
        },
        "amount_allowance": {
            "min_amount": 99.99,
            "max_amount": 999.99
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a331211c-7a48-c107-096e-870a574f0e85"
}
Get Community Commerce
GET /community_commerce

Retrieve the community commerce settings (e.g. B2B Settlement)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
settlement_settings
Object

Details about settlement settings

enable_settlement
boolean

Defines whether settlement is enabled or not

Example:
true
settlement_evaluation
string

Defines when settlement will take place

Enumeration:
REAL_TIME
HOURLY
DAILY
WEEKLY
MONTHLY
Default:
DAILY
frequency
string

The repeat frequency provided as a cron expression pattern

Example:
0 0 12 * * ?
settlement_fees
Object

Details about the settlement fee(s) that will be applied on award and/or spend transactions (applicable only if settlement is enabled)

enable_settlement_fees
boolean

Defines whether settlement fees will be applied or not

Example:
true
fee_type
string

Defines whether the related type will be amount or percentage based

Enumeration:
AMOUNT
PERCENTAGE
default_award_fee
number

Defines the default fee on award that will be applied on all organisations (merchants/service providers)

Example:
1.98
default_spend_fee
number

Defines the default fee on spend that will be applied on all organisations (merchants/service providers)

Example:
9.99
explicit_fees
Array

Defines the fees that will be applied explicitly on specific organisations (merchants/service providers)

Object
entity_type
string

Defines the entity type that fees will be explicitly applied

Enumeration:
ORGANISATION
Example:
ORGANISATION
entity
Object

Defines the entity that fees will be explicitly applied

id
string GUID

Defines the entity (identifier) that fees will be explicitly applied

Example:
4c6a4cbb-7b47-b360-0654-e50cb52bd891
name
string

Defines the entity (name) that fees will be explicitly applied

Example:
Nice Restaurant
entity_id
string

Defines the entity (identifier) that fees will be explicitly applied

Example:
3a4ff705-356d-16e4-d5f7-dd5e7c3c29d5
award_fee
number

The explicit award fee

Example:
5.91
spend_fee
number

The explicit award fee

Example:
1.99
settlement_rules
Object

Defines the settlement rules that will be applied during settlement (e.g. financial transaction types)

financial_transactions
Object

Defines the financial transaction types that will be used when posting a payment/payout during settlement

payment_type
Object

Details about the payment type that should be used for settlement

id
string GUID

The payment type identifier

Example:
e2f0f36a-a192-35b1-f2f6-363a0ace9e15
name
string

The payment type name

Example:
Settlement Payment
payout_type
Object

Details about the payout type that should be used for settlement

id
string GUID

The payout identifier

Example:
bcff5929-8bc5-10ce-0bf5-6d659c314ae2
name
string

The payout name

Example:
Settlement Payout
amount_allowance
Object

Defines the min/max amount that can be settled against an organisation account

min_amount
number

The min amount that can be settled against an organisation account

max_amount
number

The max amount that can be settled against an organisation account

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/community_commerce HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "settlement_settings": {
        "enable_settlement": "true",
        "settlement_evaluation": "DAILY",
        "frequency": "0 0 12 * * ?"
    },
    "settlement_fees": {
        "enable_settlement_fees": "true",
        "fee_type": "PERCENTAGE",
        "default_award_fee": 1.98,
        "default_spend_fee": 9.99,
        "explicit_fees": [
            {
                "entity_type": "ORGANISATION",
                "entity": {
                    "id": "4c6a4cbb-7b47-b360-0654-e50cb52bd891",
                    "name": "Nice Restaurant"
                },
                "entity_id": "3a4ff705-356d-16e4-d5f7-dd5e7c3c29d5",
                "award_fee": 5.91,
                "spend_fee": 1.99
            }
        ]
    },
    "settlement_rules": {
        "financial_transactions": {
            "payment_type": {
                "id": "e2f0f36a-a192-35b1-f2f6-363a0ace9e15",
                "name": "Settlement Payment"
            },
            "payout_type": {
                "id": "bcff5929-8bc5-10ce-0bf5-6d659c314ae2",
                "name": "Settlement Payout"
            }
        },
        "amount_allowance": {
            "min_amount": 1,
            "max_amount": 1
        }
    }
}
Get Settlement Transactions
GET /settlement_transactions

Retrieve the settlement transactions related to B2B Settlement

Request parameters

settlement_type
string optional

Filter based on the settlement transaction type

Enumeration:
AWARD

Award Transaction

SPEND

Spend Transaction

AWARD_FEE

Award Settlement Fee

SPEND_FEE

Spend Settlement Fee

accounting_type
string optional

Filter based on the accounting transaction type

Enumeration:
DEBIT
CREDIT
status
string optional

Filter based on settlement transaction status

Enumeration:
POSTED
CANCELLED
organisation_id
string GUID optional

Filters based on the organisation (identifier) that the settlement transaction is posted against

Example:
71c42a44-f8ce-919c-074e-b0a213ca3885
created_on
string optional

Filter based on the created date, which may fall within a given date range. The value can be a string with a date in epoch format. Each option must also include an operator. Use up to two options based on the required search (e.g. created_on[gte]=1618395497&created_on[lt]=1618395497).

Enumeration:
created_on[gt]

Returns results where the created date is greater than this value

created_on[gte]

Returns results where the created date is greater than or equal to this value

created_on[lt]

Returns results where the created date is less than this value

created_on[lte]

Returns results where the created date is less then or equal to this value

account_journal_entry_id
string GUID optional

Filter based on an account journal entry

Example:
4c156688-4d53-d0e4-e483-1809cacaaaca
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The settlement transaction identifier

Example:
daf23f03-e267-fe94-9965-5c81e9ab4a4d
settlement_type
string

Defines the settlement transaction type

Enumeration:
AWARD

Award Transaction

SPEND

Spend Transaction

AWARD_FEE

Award Settlement Fee

SPEND_FEE

Spend Settlement Fee

accounting_type
string

Defines the accounting type of the settlement transaction

Enumeration:
DEBIT
CREDIT
status
string

The settlement transaction status

Enumeration:
POSTED
CANCELLED
event_amount
number

The initial amount to be settled (before applying the applicable contribution/settlement fee)

Example:
2.22
settlement_amount
number

The amount to be settled (after contribution/settlement fee is applied)

Example:
20.12
fee
Object

The contribution/settlement fee that was applied on the settlement transaction

fee_type
string

Defines the fee type

Enumeration:
CONTRIBUTION

Contribution fee, applied on award transactions

SETTLEMENT

Settlement fee, applied on award/spend transactions

value_type
string

Defines whether the fee is amount or percentage based

Enumeration:
AMOUNT

Fee will be amount based

PERCENTAGE

Fee will be percentage based

value
number

The fee value

Example:
2.84
organisation
Object

The organisation that the settlement transaction is posted against

type
string

The organisation type

Enumeration:
MERCHANT
id
string GUID

The organisation identifier

Example:
f2c2d9ea-5a94-729d-0c45-7fdd1d540e7b
name
string

The organisation name

Example:
CRM
settlement_event
Object

Details about the event that initiated such settlement request

type
string

Defines the type of the event that is related to the settlement transaction

Enumeration:
PURCHASE
id
string GUID

The event identifier

Example:
598c02d3-1978-3585-3a3b-2311d6c94d1c
reference_number
string

The event reference number/code (if applicable)

Example:
2833205645375343
amount
number

The event amount

Example:
102.79
posted_date
integer epoch

The date on which the event was posted

Example:
1635170879
reward_offer
Object

Details about the reward offer (related to the award type)

id
string GUID

The reward offer identifier

Example:
1b5f5824-e05f-bb8e-d2ee-19eb5ed83240
name
string

The reward offer name

Example:
10% instant discount
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/settlement_transactions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "daf23f03-e267-fe94-9965-5c81e9ab4a4d",
            "settlement_type": "AWARD",
            "accounting_type": "CREDIT",
            "event_amount": 2.22,
            "settlement_amount": 20.12,
            "fee": {
                "fee_type": "CONTRIBUTION",
                "value_type": "AMOUNT",
                "value": 2.84
            },
            "organisation": {
                "type": "MERCHANT",
                "id": "f2c2d9ea-5a94-729d-0c45-7fdd1d540e7b",
                "name": "CRM"
            },
            "settlement_event": {
                "type": "PURCHASE",
                "id": "598c02d3-1978-3585-3a3b-2311d6c94d1c",
                "reference_number": "2833205645375343",
                "amount": 102.79,
                "posted_date": 1635170879
            },
            "reward_offer": {
                "id": "1b5f5824-e05f-bb8e-d2ee-19eb5ed83240",
                "name": "10% instant discount"
            }
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Teams
POST /teams
PUT /teams/{id}
DELETE /teams/{id}
GET /teams
GET /teams/{id}
Create Team
POST /teams

Create a new team

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The team name

Example:
Admin
description
string nullable

The team description

Example:
Admin Team

Responses

200 OK
Body
Object
id
string GUID

The team identifier

Example:
609de9a4-8220-be54-63ca-a7044b1326e0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/teams HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Admin",
    "description": "Admin Team"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "609de9a4-8220-be54-63ca-a7044b1326e0"
}
Update Team
PUT /teams/{id}

Update an existing team

Path variables

id
string GUID required

The team (identifer) that will be updated

Example:
dfdeb9f9-003d-fca7-c548-0a88676bb9cf

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The team name

Example:
Admin
description
string nullable

The team description

Example:
Admin Team

Responses

200 OK
Body
Object
id
string GUID

The team identifier

Example:
609de9a4-8220-be54-63ca-a7044b1326e0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/teams/dfdeb9f9-003d-fca7-c548-0a88676bb9cf HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Admin",
    "description": "Admin Team"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "609de9a4-8220-be54-63ca-a7044b1326e0"
}
Delete Team
DELETE /teams/{id}

Delete an existing team

Path variables

id
string GUID required

The team (identifer) that will be deleted

Example:
dfdeb9f9-003d-fca7-c548-0a88676bb9cf

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/teams/dfdeb9f9-003d-fca7-c548-0a88676bb9cf HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Teams
GET /teams

Search for teams

Request parameters

name
string optional

Filters based on the team name

Example:
Admin
users_count
boolean optional

Defines whether the number of users per team will be retrieved

Example:
true
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The team identifier

Example:
a9dca18e-1d60-8d5b-cf46-848d9fa91dd6
name
string

The team name

Example:
Admin
description
string

The team description

Example:
Admin Team
users_count
integer

The number of users that belong to the team

Example:
112
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/teams HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "a9dca18e-1d60-8d5b-cf46-848d9fa91dd6",
            "name": "Admin",
            "description": "Admin Team"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Team
GET /teams/{id}

Get details for a specific team

Path variables

id
string GUID required

The team (identifer) that will be retrieved

Example:
d64e7544-aba8-d6de-f8d0-54e02b1daba3

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The team identifier

Example:
6646193b-9177-1d1a-aca9-7c16ee67e786
name
string

The team name

Example:
Admin
description
string

The team description

Example:
Admin Team Description
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/teams/d64e7544-aba8-d6de-f8d0-54e02b1daba3 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "6646193b-9177-1d1a-aca9-7c16ee67e786",
    "name": "Admin",
    "description": "Admin Team Description"
}
Communications
PUT /tracking_settings
GET /tracking_settings
Update tracking settings
PUT /tracking_settings

Updates the tracking settings of communications

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

application/json
Object
enable_tracking
boolean

Enables the tracking functionality

Example:
true
track_end_point
string
track_custom_url
string
email_tracking_mode
string
Enumeration:
ALL
COMM_PLANS
link_tracking_mode
string
Enumeration:
ALL
COMM_PLANS

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/tracking_settings HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "enable_tracking": true,
    "track_end_point": "",
    "track_custom_url": "",
    "email_tracking_mode": "ALL",
    "link_tracking_mode": "ALL"
}

HTTP/1.1 200 OK 
Get tracking settings
GET /tracking_settings

Retrieves the tracking settings for communications

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
application/json
Object
enable_tracking
boolean

Enables the tracking functionality

Example:
true
track_end_point
string
track_custom_url
string
email_tracking_mode
string
Enumeration:
ALL
COMM_PLANS
link_tracking_mode
string
Enumeration:
ALL
COMM_PLANS
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/tracking_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "enable_tracking": true,
    "track_end_point": "",
    "track_custom_url": "",
    "email_tracking_mode": "ALL",
    "link_tracking_mode": "COMM_PLANS"
}
Contacts
PUT /contact_generic_settings
GET /contact_generic_settings
POST /name_day_rules
PUT /name_day_rules/{name_day_rule_id}
DELETE /name_day_rule/{name_day_rule_id}
GET /name_day_rules
Update Contact Generic Settings
PUT /contact_generic_settings

Update the generic contact settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name_display_settings
string

The settings which defines how the names are presented in the system

Enumeration:
FIRST_LAST
LAST_FIRST
FIRST_MIDDLE_LAST
LAST_MIDDLE_FIRST
cim_settings
Array
Object
medium
string
Enumeration:
CARD
EMAIL
PHONE
GIFT_PASS
is_enabled
boolean
consent_settings
Object
enable_consent
boolean

Enable consent functionality so that the Contact accepts/rejects/withdraws it. Default value is FALSE.

functionality_on_pending
string
Enumeration:
NO_FUNCTIONALITY
FULL_FUNCTIONALITY
functionality_on_rejecting
string
Enumeration:
NO_FUNTIONALITY
FULL_FUNCTIONALITY
ANONYMIZE
functionality_on_withdraw
string
Enumeration:
NO_FUNTIONALITY
FULL_FUNCTIONALITY
ANONYMIZE
identities_settings
Object nullable

Contact Identities settings, applying additional security precautions

require_verification
boolean required

Defines whether credentials (username&password) will require verification or not

Default:
true
Example:
false

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the organisation

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/contact_generic_settings HTTP/1.1 

Content-Type: application/json

{
    "name_display_settings": "FIRST_LAST",
    "cim_settings": [
        {
            "medium": "EMAIL",
            "is_enabled": true
        }
    ],
    "consent_settings": {
        "enable_consent": true,
        "functionality_on_pending": "FULL_FUNCTIONALITY",
        "functionality_on_rejecting": "ANONYMIZE",
        "functionality_on_withdraw": "FULL_FUNCTIONALITY"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Get Contact Generic Settings
GET /contact_generic_settings

Returns the general settings of the contact

Responses

200 200

The request has succeeded

Body
Object
name_display_settings
string

The name display settings that define how the contact name is presented

Enumeration:
FIRST_LAST
LAST_FIRST
FIRST_MIDDLE_LAST
LAST_MIDDLE_FIRST
cim_settings
Array
Object
medium
string
Enumeration:
CARD
PHONE
EMAIL
GIFT_PASS
is_enabled
boolean
consent_settings
Object
is_enabled
boolean
functionality_on_pending
string
Enumeration:
NO_FUNCTIONALITY
FULL_FUNCTIONALITY
functionality_on_rejecting
string
Enumeration:
NO_FUNCTIONALITY
FULL_FUNCTIONALITY
ANONYMIZE
functionality_on_withdraw
string
Enumeration:
NO_FUNTIONALITY
FULL_FUNCTIONALITY
ANONYMIZE
consent_file_url
string
identities_settings
Object

Contact Identities settings, applying additional security precautions

require_verification
boolean

Defines whether credentials (username&password) will require verification or not

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/contact_generic_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name_display_settings": "FIRST_MIDDLE_LAST",
    "cim_settings": [
        {
            "medium": "CARD",
            "is_enabled": true
        }
    ],
    "consent_settings": {
        "is_enabled": true,
        "functionality_on_pending": "FULL_FUNCTIONALITY",
        "functionality_on_rejecting": "ANONYMIZE",
        "functionality_on_withdraw": "ANONYMIZE",
        "consent_file_url": ""
    }
}
Create Name Day Rules
POST /name_day_rules

Create the name day rules

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
day
number

The day of the name day (1-31)

Example:
15
month
number

The month of the name day (1-12)

Example:
8
names
string

A list of names that celebrate the specific name day, comma separated

Example:
Mario, Maria, Panayiota
description
string

A description of the name day

Example:
Holly Mary

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the name day rule created

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Name Day Rules
PUT /name_day_rules/{name_day_rule_id}

Update the name day rules

Path variables

name_day_rule_id
string GUID required
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
day
number

The day of the name day (1-31)

Example:
15
month
number

The month of the name day (1-12)

Example:
8
names
string

A list of names that celebrate the specific name day, comma separated

Example:
Mario, Maria, Panayiota
description
string

A description of the name day

Example:
Holly Mary

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the name day rules

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Delete Name Day Rule
DELETE /name_day_rule/{name_day_rule_id}

Delete a name day rule

Path variables

name_day_rule_id
string required
Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the organisation

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Name Day Rules
GET /name_day_rules

Retrieve the contact name day rules

Request parameters

first_name
string optional

The first name of the contact to retrieve only applicable name days

Example:
Marios
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
name_day_rules
Array
Object
id
string

The unique identification of the name day rule

day
integer

The day of the name day rule

month
integer

The month of the name day rule

names
string

The names that celebrate this name day, comma separated

Example:
Marios, Maria
description
string

A description of the name day

Example:
Holly Mary
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Contact Categories
POST /contact_categories
PUT /contact_categories/{category_id}
DELETE /contact_categories/{category_id}
GET /contact_categories
Create Contact Category
POST /contact_categories

Create the contact categories

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the category to be created

Example:
VIP

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Update Contact Category
PUT /contact_categories/{category_id}

Update a specific contact category

Path variables

category_id
string GUID required

The contact category identifier that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the category

Example:
VIP

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the contact category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Delete Contact Category
DELETE /contact_categories/{category_id}

Update a specific contact category

Path variables

category_id
string GUID required

The contact category identifier that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Contact Categories
GET /contact_categories

List all the available contact categories

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC
name
string optional

The name of the contact category

Example:
VIP

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Array
Object
category_id
string GUID

The ID of the contact category

Example:
4AD9C84FA60F9FE407140E20F707726A
category_name
string

The name of the contact category

Example:
VIP
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Contact KYC Profile
POST /kyc_profiles
PUT /kyc_profiles/{id}
DELETE /kyc_profiles/{id}
GET /kyc_profiles
Create KYC Profile
POST /kyc_profiles

Create a single KYC profile

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the KYC profile

Example:
Standard Customers
description
string

A description of the KYC profile

Example:
The KYC Profile
conditions
Array

The conditions for which the kyc profile is applied

Object
name
string

The entity for which the condition applies

Enumeration:
ACCOUNT_CLASSIFICATION
KYC_PROFILE
CONTACT_CATEGORY
value
string

The entity’s ID or Name

Example:
4AD9C84FA60F9FE407140E20F707726A
fields
Array

Define the sets of fields that are required to verify the KYC profile. The sets are combined with an OR

Object
sets
Array

The fields that are included within a set (combined with AND). It can be any custome field value OR an existing contact field

string
Enumeration:
first_name
middle_name
last_name
company_name
statutory_number
passport_number
id_number
email_address
..any custom field value

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the KYC profile

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/kyc_profiles HTTP/1.1 

Content-Type: application/json

{
    "name": "Standard Customers",
    "description": "The KYC Profile",
    "conditions": [
        {
            "name": "CONTACT_CATEGORY",
            "value": "4AD9C84FA60F9FE407140E20F707726A"
        }
    ],
    "fields": [
        {
            "sets": [
                "first_name"
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update KYC Profile
PUT /kyc_profiles/{id}

Update an existing KYC profile. Profiles that are already provided on at least one contact, cannot be updated

Path variables

id
string GUID required

The ID of the KYC profile to be updated

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the KYC profile

Example:
Standard Customers
description
string

A description of the KYC profile

Example:
The KYC Profile
conditions
Array

The conditions for which the kyc profile is applied

Object
name
string

The entity for which the condition applies

Enumeration:
ACCOUNT_CLASSIFICATION
KYC_PROFILE
CONTACT_CATEGORY
value
string

The entity’s ID or Name

Example:
4AD9C84FA60F9FE407140E20F707726A
fields
Array

Define the sets of fields that are required to verify the KYC profile. The sets are combined with an OR

Object
sets
Array

The fields that are included within a set (combined with AND). It can be any custome field value OR an existing contact field

string
Enumeration:
first_name
middle_name
last_name
company_name
statutory_number
passport_number
id_number
email_address
..any custom field value

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the KYC profile

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/kyc_profiles/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

Content-Type: application/json

{
    "name": "Standard Customers",
    "description": "The KYC Profile",
    "conditions": [
        {
            "name": "ACCOUNT_CLASSIFICATION",
            "value": "4AD9C84FA60F9FE407140E20F707726A"
        }
    ],
    "fields": [
        {
            "sets": [
                "passport_number"
            ]
        }
    ]
}
Delete KYC Profile
DELETE /kyc_profiles/{id}

Delete an existing KYC profile validating that is not already used on at least one Contact

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/kyc_profiles/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List KYC Profiles
GET /kyc_profiles

List all available KYC Profiles

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for KYC Profiles across their Names

Example:
Standard

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The ID of the KYC profile

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the KYC profile

Example:
Standard Customers
description
string

A description of the KYC profile

Example:
The KYC Profile
conditions
Array

The conditions for which the kyc profile is applied

Object
name
string

The entity for which the condition applies

Enumeration:
ACCOUNT_CLASSIFICATION
KYC_PROFILE
CONTACT_CATEGORY
value
string
Example:
4AD9C84FA60F9FE407140E20F707726A
fields
Array

Define the sets of fields that are required to verify the KYC profile. The sets are combined with an OR

Object
sets
Array

The fields that are included within a set (combined with AND). It can be any custome field value OR an existing contact field

string
Enumeration:
first_name
middle_name
last_name
company_name
statutory_number
passport_number
id_number
email_address
..any custom field value
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/kyc_profiles HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Standard Customers",
            "description": "The KYC Profile",
            "conditions": [
                {
                    "name": "ACCOUNT_CLASSIFICATION",
                    "value": "4AD9C84FA60F9FE407140E20F707726A"
                }
            ],
            "fields": [
                {
                    "sets": [
                        "..any custom field value"
                    ]
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Contact Mandatory Fields
POST /contact_mandatory_fields
Update Contact Mandatory Fields
POST /contact_mandatory_fields

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
mandatory_field
string

Defines the field that is mandatory during contact registration

Enumeration:
BIRTHDATE
NAMEDAY
GENDER
is_mandatory
boolean

Defiend whether the field is mandatory during contact registration

Example:
true
Customer Events
PUT /customer_event_generic_settings
GET /customer_event_generic_settings
Set Customer Event Settings
PUT /customer_event_generic_settings

Update the generic customer event settings for an organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
purchase_settings
Object nullable

Information about handling invalid product information on purchase customer events

invalid_product_type_id
string GUID nullable

The product type identifier that will be used when creating invalid products from purchase customer events

Default:
Invalid Purchase Products
Example:
QWERTY1234543212345678UJIKY76HJR

Responses

200 200

Successful Request

Body
Object
id
string GUID

The organisation identifier

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /customer_event_generic_settings HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "purchase_settings": {
        "invalid_product_type_id": "QWERTY1234543212345678UJIKY76HJR"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "QWERTY1234543212345678UJIKY76HJR"
}
Get Customer Event Settings
GET /customer_event_generic_settings

Retrieve the generic customer event settings for an organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
purchase_settings
Object

Information about handling invalid product information on purchase customer events

invalid_product_type_id
string GUID

The product type identifier that will be used when creating invalid products from purchase customer events

Example:
QWERTY1234543212345678UJIKY76HJR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /customer_event_generic_settings HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "purchase_settings": {
        "invalid_product_type_id": "QWERTY1234543212345678UJIKY76HJR"
    }
}
Customer Event Classifications
POST /customer_event_classifications
PUT /customer_event_classifications/{id}
DELETE /customer_event_classifications/{id}
GET /customer_event_classifications
GET /customer_event_classifications/{id}
Create Customer Event Classification
POST /customer_event_classifications

Create a customer event classification within a single organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The classification name

Example:
Cash
description
string nullable

The classification description

Example:
Cash driven customer event
type
string required

The classification type

Enumeration:
PURCHASE
ACHIEVEMENT

Responses

200 200

Successful Request

Body
Object
id
string GUID

The classification identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /customer_event_classification HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Cash",
    "description": "Cash driven customer event",
    "type": "REFERRAL"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Customer Event Classification
PUT /customer_event_classifications/{id}

Update a specific contact classification for a specific organisation

Path variables

id
string GUID required

The customer event classification (identifier) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the classification

Example:
Cash
description
string nullable

The description of the classification

Example:
Represent cash driven customer events

Responses

200 200

Successful Request

Body
Object
id
string GUID

The classification identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /customer_event_classifications/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Cash",
    "description": "Represent cash driven customer events"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Customer Event Classification
DELETE /customer_event_classifications/{id}

Delete a specific customer event classification for a specific organisation

Path variables

id
string GUID required

The customer event classification (identifier) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /customer_event_classifications/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List Customer Event Classifications
GET /customer_event_classifications

Search for customer event classifications within a single organisation

Request parameters

name
string optional

The name of the classification

Example:
Cash
type
string optional

The type of the classification

Enumeration:
PURCHASE
ACHIEVEMENT
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The classification identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the classification

Example:
Cash
description
string

The description of the classification

Example:
Cash driven customer event
type
string

The type of the classification

Enumeration:
PURCHASE
ACHIEVEMENT
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /customer_event_classifications HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Cash",
            "description": "Cash driven customer event",
            "type": "KPI_PERFORMANCE"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Customer Event Classification
GET /customer_event_classifications/{id}

Get details for a single customer event classification

Path variables

id
string GUID required

The classification (identifier) that will be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The classification identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the classification

Example:
Cash
description
string

The description of the classification

Example:
Cash driven customer event
type
string

The type of the classification

Enumeration:
PURCHASE
ACHIEVEMENT
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /customer_event_classifications/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A",
    "name": "Cash",
    "description": "Cash driven customer event",
    "type": "KPI_PERFORMANCE"
}
Financial Transactions
GET /financial_settings
PUT /financial_settings
POST /financial_transaction_types
PUT /financial_transaction_types/{id}
DELETE /financial_transaction_types/{id}
GET /financial_transaction_types
Get Financial Settings
GET /financial_settings

Get the generic financial settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
tax_model
string

The default tax model that is automatically set when setting up product prices

Enumeration:
TAX_INCLUSIVE

Prices include taxes

TAX_EXCLUSIVE

Prices does not include tax

Default:
TAX_INCLUSIVE
Example:
TAX_INCLUSIVE
payment_retries
Object

Business rules that enable a payment retry attempt on failing to pay off an invoice or a subscription

enable
boolean required

Enable payment retries

Default:
false
Example:
true
frequency
Object required

How often an attempt will be perfomed right after a payment failure

value
integer required

The frequency value

Example:
1
uot
string required

The frequency’s unit of time

Enumeration:
HOURS
DAYS
Default:
HOURS
Example:
HOURS
retries
integer required

How many payment attempts will be performed

Example:
3
maximum_period
Object

The maximum period of time that the system will retry. A payment retry will not be performed if maximum period of time is reached and regardless of the fact that not all retries were perforemd.

period
integer required

The period of time

Example:
3
uot
string required

Period of time unit of time

Enumeration:
HOURS
DAYS
Default:
DAYS
Example:
DAYS
subscription_action
string required nullable

Defines what happens to the subscription of all payment retries fail

Enumeration:
REMAINS_AS_IS
DEACTIVATE
Default:
DEACTIVATE
payment_methods
Array

The allowed payment method types that can be used across the system

Object
type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
is_allowed
boolean

Defines whether the payment method type is allowed or not. Not allowed types canno tbe used when adding contac tpayment methods, posting payments etc

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/financial_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tax_model": "TAX_INCLUSIVE",
    "payment_retries": {
        "enable": true,
        "frequency": {
            "value": 1,
            "uot": "HOURS"
        },
        "retries": 3,
        "maximum_period": {
            "period": 3,
            "uot": "DAYS"
        },
        "subscription_action": "DEACTIVATE"
    },
    "payment_methods": [
        {
            "type": "WALLET",
            "is_allowed": "false"
        }
    ]
}
Update Financial Settings
PUT /financial_settings

Update the generic financial settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
tax_model
string required

The default tax model that is automatically set when setting up product prices

Enumeration:
TAX_INCLUSIVE

Prices include taxes

TAX_EXCLUSVE

Prices do not include taxes

payment_retries
Object

Business rules that enable a payment retry attempt on failing to pay off an invoice or a subscription

enable
boolean required

Enable payment retries

Default:
false
Example:
true
frequency
Object

How often an attempt will be perfomed right after a payment failure

value
integer required

The frequency value

Example:
1
uot
string required

The frequency’s unit of time

Enumeration:
HOURS
DAYS
Default:
HOURS
retries
integer required

How many payment attempts will be performed

Example:
3
maximum_period
Object

The maximum period of time that the system will retry. A payment retry will not be performed if maximum period of time is reached ad regardless of the fact that not all retries were perforemd.

period
integer required

The period’s value

Example:
3
uot
string required

Period of time unit of time

Enumeration:
HOURS
DAYS
WEEKS
Default:
DAYS
Example:
DAYS
subscription_action
string nullable

Defines what happens to the subscription of all payment retries fail

Enumeration:
REMAINS_AS_IS
DEACTIVATE
Default:
DEACTIVATE
Example:
DEACTIVATE
payment_methods
Array
Object
type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE

Responses

200 200

Successful Request

Body
Object
id
string

Unique identifier of financial Settings

Example:
81560181-f08f-4a83-a683-8ca6555b608a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/financial_settings HTTP/1.1 

Content-Type: application/json

{
    "tax_model": "TAX_INCLUSIVE",
    "payment_retries": {
        "enable": true,
        "frequency": {
            "value": 1,
            "uot": "HOURS"
        },
        "retries": 3,
        "maximum_period": {
            "period": 3,
            "uot": "DAYS"
        },
        "subscription_action": "DEACTIVATE"
    },
    "payment_methods": [
        {
            "type": "ACCOUNT_DEBIT"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "81560181-f08f-4a83-a683-8ca6555b608a"
}
Create Financial Transactions Type
POST /financial_transaction_types

Create the financial transaction types

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the financial transaction type

Example:
INVOICE
classification
string

The type of the event

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
PAYOUT
Example:
INVOICE
is_default
boolean

Sets the financial transaction type as the default of its classification

Example:
true
description
string

A description of the financial transaction type

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction type

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/financial_transaction_types HTTP/1.1 

Content-Type: application/json

{
    "name": "INVOICE",
    "classification": "INVOICE",
    "is_default": "true",
    "description": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Financial Transaction Type
PUT /financial_transaction_types/{id}

Update the financial transaction type

Path variables

id
string required

The id of the financial transaction type to be updated

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the financial transaction type

Example:
INVOICE
is_default
boolean

Sets the financial transaction type as the default of its classification

Example:
true
description
string

A description of the financial transaction type

Responses

200 200

Successful Request

Body
Object
id
string

The unique identifier of the financial transaction type

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/financial_transaction_types/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "INVOICE",
    "is_default": "true",
    "description": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Financial Transaction Type
DELETE /financial_transaction_types/{id}

Delete a financial transaction type

Path variables

id
string required

The id of the financial transaction type to be deleted

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/financial_transactions_types/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List Financial Transaction Types
GET /financial_transaction_types

Get all the available financial transaction types

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

The value of the search across name, classification (case insensitive)

Example:
DEBIT
classification
string optional

The classification of the financial transaction

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
PAYOUT
Example:
INVOICE
is_default
boolean optional

Filters only the default types

Example:
true

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
name
string

The name of the financial transaction type

Example:
INVOICE
classification
string

The type of the event

Enumeration:
INVOICE
CREDIT_NOTE
PAYMENT
REFUND
PAYOUT
Example:
INVOICE
is_default
boolean

Sets the financial transaction tyep as the default of its classification

Example:
true
description
string

A description of the financial transaction type

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/financial_transaction_types HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "INVOICE",
            "classification": "INVOICE",
            "is_default": "true",
            "description": ""
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Inventory
Device Statuses
POST /device_statuses
PUT /device_statuses/{id}
DELETE /device_statuses/{id}
GET /device_statuses
Create Device Status
POST /device_statuses

Creates devices status

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the device status

Example:
Refurbished
description
string

A description of the device status

Example:
Devices that have been fixed and will be sold with discount
classification
string

Defines ones of the default statuses, that the specific one will clone its behaviour

Enumeration:
AVAILABLE
INACTIVE
SOLD
RENTED
USED
OWN_DEVICE
is_default
boolean

Defines which status is the default one used by the system

Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the device status

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/device_statuses HTTP/1.1 

Content-Type: application/json

{
    "name": "Refurbished",
    "description": "Devices that have been fixed and will be sold with discount",
    "cloned_status": "AVAILABLE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update Device Status
PUT /device_statuses/{id}

Updates an additional device status

Path variables

id
string GUID required

The ID of the device status

Example:
4AD9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the device status

Example:
Refurbished
description
string nullable

A description of the device status

Example:
Devices that have been fixed and will be sold with discount
is_default
boolean nullable

Defines which status is the default one used by the system

Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The unique identifier of the device status

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/device_statuses HTTP/1.1 

Content-Type: application/json

{
    "name": "Refurbished",
    "description": "Devices that have been fixed and will be sold with discount",
    "cloned_status": "INACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Delete Device Status
DELETE /device_statuses/{id}

Delete an existing device status

Path variables

id
string GUID required

The device status (identifier) to be deleted

Example:
db6939af-9e6a-8cf9-4bba-4ef58677dc6b

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/device_statuses/4AD9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 
List Device Statuses
GET /device_statuses

Retrieve a list of device statuses based on search criteria (e.g. all used device statuses)

Request parameters

search_value
string optional

Filter based on device status attributes (name and classification)

Example:
new status
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
name
string

The name of the device status

Example:
Refurbished
description
string

A description of the device status

Example:
Devices that have been fixed and will be sold with discount
classification
string

Defines ones of the default statuses, that the specific one will clone its behaviour.

Enumeration:
AVAILABLE
INACTIVE
SOLD
RENTED
USED
OWN_DEVICE
is_default
boolean

Defines whether the status is the default one used by the system

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/device_statuses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "Refurbished",
            "description": "Devices that have been fixed and will be sold with discount",
            "cloned_status": "IMPORTED"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Leads

Leads configurations.

Lost Reasons
POST /lost_reasons
PUT /lost_reasons/{id}
DELETE /lost_reasons/{id}
GET /lost_reasons
Create Lost Reason
POST /lost_reasons

Create a possible reason for losing a lead

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

A unique name for the lost reason

Example:
Requirements
description
string

A description for the lost reason

Example:
The product does not meet customer's requirements
Examples

Responses

201 Created
Body
Object
id
string GUID

The unique identifier of the newly created lost reason

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/lost_reasons HTTP/1.1 

Content-Type: application/json

{
    "name": "Requirements",
    "description": "The product does not meet customer's requirements"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Update Lost Reason
PUT /lost_reasons/{id}

Update a lost (lead) reason

Path variables

id
string GUID required

The GUID of the lost reason to be updated

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

A unique lost reason name

Example:
Too expensive
description
string

A description of the lost lead reason

Example:
Pricing is not within organisation's budget.
Examples

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated lost reason

Example:
74D9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/lost_reasons/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

Content-Type: application/json

{
    "name": "Too expensive",
    "description": "Pricing is not within organisation's budget."
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "74D9C84FA60F9FE407140E20F707726A"
}
Delete Lost Reason
DELETE /lost_reasons/{id}

Delete a lost lead reason

Path variables

id
string required

The GUID of the lost reason to be deleted

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/lost_reasons/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 
List Lost Reasons
GET /lost_reasons

List all available reasons for losing a lead

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for a lost reason based on its name and description

Example:
pricing

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The GUID of the lost reason

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

The name of the lost reason

Example:
Pricing
description
string

The description of the lost reason

Example:
Pricing not within organisation's budget
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/lost_reasons?search_value=pricing HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Pricing",
            "description": "Pricing not within organisation's budget"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Pipelines
POST /pipelines
PUT /pipelines/{id}
GET /pipelines
GET /pipelines/{id}
DELETE /pipelines/{id}
PUT /pipelines/{id}/actions
DELETE /pipelines/{id}/pipeline_stages/{stage_id}
Create Pipeline
POST /pipelines

Create a pipeline with it’s stages to be used for leads.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A unique name for the lead queue

Example:
European subscriptions lead
pipeline_stages
Array

The pipeline’s stages

Object
name
string

Stage name

Example:
Proposal Submitted
stage_order
string

The order of the stage within the queue

Example:
4
Examples

Responses

201 Created
Body
Object
id
string

The unique identifier of the newly created pipeline

Example:
V349C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/pipelines HTTP/1.1 

Content-Type: application/json

{
    "name": "European subscriptions lead",
    "pipeline_stages": [
        {
            "name": "Proposal Submitted",
            "stage_order": "4"
        }
    ]
}
Update Pipeline
PUT /pipelines/{id}

Update a lead’s queue and it’s statuses

Path variables

id
string GUID required

The GUID of the pipeline to be updated

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The unique pipeline name

Example:
Large-scale business lead
pipeline_stages
Array

The stages of the pipeline

Object
name
string

Pipeline stage name

Example:
Proposal Submitted
stage_order
integer

Order of the stage within the pipeline

Example:
4
Examples

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated pipeline

Example:
74D9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/pipelines/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

Content-Type: application/json

{
    "name": "Large-scale business lead",
    "pipeline_stages": [
        {
            "name": "Proposal Submitted",
            "stage_order": 4
        }
    ]
}
List Pipelines
GET /pipelines

Retrieve all pipelines

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for a pipeline using it’s name

Example:
Small-Medium local businesses

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The GUID of the pipeline

Example:
74D9C84FA60F9FE407140E20F707726A
name
string

The name of the pipeline

Example:
Small local business lead
life_cycle_state
string

The life cycle state of the pipeline

Example:
Effective
number_of_stages
integer

Number of stages that the pipeline contains

Example:
5
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/pipelines HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "74D9C84FA60F9FE407140E20F707726A",
            "name": "Small local business lead",
            "life_cycle_state": "Effective",
            "number_of_stages": 5
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Pipeline
GET /pipelines/{id}

Retrieve a pipeline and it’s stages

Path variables

id
string GUID required

The GUID of the pipeline

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The GUID of the retrieved pipeline

name
string

The pipeline name

Example:
Small local business lead
life_cycle_state
string

The life cycle state of the pipeline

Example:
Effective
pipeline_stages
Array

The pipeline’s stages

Object
id
string GUID

Pipeline stage GUID

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

Pipeline stage name

Example:
Proposal submitted
stage_order
integer

The order of the stage within the pipeline

Example:
5
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/pipelines/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "name": "Small local business lead",
    "life_cycle_state": "Effective",
    "pipeline_stages": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Proposal submitted",
            "stage_order": 5
        }
    ]
}
Delete a Pipeline
DELETE /pipelines/{id}

Delete a pipeline

Path variables

id
string required

The GUID of the pipeline to be deleted

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/pipelines/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 
Pipeline Actions
PUT /pipelines/{id}/actions

Actions to be taken for a leads queue

Path variables

id
string GUID required

The GUID of the pipeline to take action on

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The action to be performed

Enumeration:
LIFE_CYCLE_STATE

Upate the life cycle state of a queue

life_cycle_state
string

The new life cycle state (required only if the action is LIFE_CYCLE_STATE)

Enumeration:
EFFECTIVE

The queue can be assigned to leads

NOT_EFFECTIVE

The queue cannot be assigned to leads

Examples

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated pipeline

Example:
74D9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/pipelines/74D9C84FA60F9FE407140E20F707726A/actions HTTP/1.1 

Content-Type: application/json

{
    "action": "LIFE_CYCLE_STATE",
    "life_cycle_state": "NOT_EFFECTIVE"
}
Delete Pipeline Stage
DELETE /pipelines/{id}/pipeline_stages/{stage_id}

Delete a pipeline stage

Path variables

id
string required

The GUID of the pipeline

Example:
74D9C84FA60F9FE407140E20F707726A
stage_id
string required

The GUID of the pipeline stage to be deleted

Example:
PR90C84FA60F9FE407140E20F7077277

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
new_stage_id
string required

The GUID of the new pipeline stage to which any existing Leads will be transferred to

Example:
407140E20F7077277PR90C84FA60F9FE

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/pipelines/74D9C84FA60F9FE407140E20F707726A/pipeline_stages/PR90C84FA60F9FE407140E20F7077277 HTTP/1.1 

Content-Type: application/json

{
    "new_stage_id": "407140E20F7077277PR90C84FA60F9FE"
}
Licenses
POST /licenses
PUT /licenses/{id}
DELETE /licenses/{id}
GET /organisations/{id}/licenses
GET /licenses/{license_id}
POST /licenses/{id}/actions
POST /licenses/{id}/assets
POST /assets
GET /assets
GET /assets/{id}
PUT /assets/{id}
DELETE /assets/{id}
Create License
POST /licenses

Create a new license

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the license

Example:
Trial License
description
string nullable

The description of the license

Example:
This is free Trial License with limited access to features

Responses

200 OK
Body
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/licenses HTTP/1.1 

Content-Type: application/json

{
    "name": "Trial License",
    "description": "This is free Trial License with limited access to features"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42f3752c-676a-8245-1c87-130b93f960c7"
}
Update License
PUT /licenses/{id}

Update a license

Path variables

id
string GUID required

The identifier of the license that will be updated

Example:
42f3752c-676a-8245-1c87-130b93f960c7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the license

Example:
Trial License
description
string nullable

The description of the license

Example:
This is free Trial License with limited access to features

Responses

200 OK
Body
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/licenses/42f3752c-676a-8245-1c87-130b93f960c7 HTTP/1.1 

Content-Type: application/json

{
    "name": "Trial License",
    "description": "This is free Trial License with limited access to features"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42f3752c-676a-8245-1c87-130b93f960c7"
}
Delete License
DELETE /licenses/{id}

Delete a single license

Path variables

id
string GUID required

The license (identifier) that will be deleted

Example:
42f3752c-676a-8245-1c87-130b93f960c7

Responses

200 OK

Successfull Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/licenses/42f3752c-676a-8245-1c87-130b93f960c7 HTTP/1.1 

HTTP/1.1 200 OK 
List Licenses
GET /organisations/{id}/licenses

Returns a list of licenses of the organisation

Path variables

id
string GUID required

The oginasation identifier

Example:
d332dd8a-254e-47c9-ba1f-3f369877a9b3

Request parameters

search_value
string optional

Search for license based on name and description

Example:
Trial License
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
name
string

The name of the license

Example:
Trial License
description
string

The description of the license

Example:
This is free Trial License with limited access to features
life_cycle_state
string

The life cycle state of the license

Enumeration:
ACTIVE
INACTIVE
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organization/d332dd8a-254e-47c9-ba1f-3f369877a9b3/licenses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "42f3752c-676a-8245-1c87-130b93f960c7",
            "name": "Trial License",
            "description": "The is  Trial License",
            "life_cycle_state": "ACTIVE"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get License
GET /licenses/{license_id}

Returns the details of a license of the organisation.

Path variables

license_id
string GUID required

The license (identifier) for which information will be retreived

Example:
42f3752c-676a-8245-1c87-130b93f960c7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

Successful Request

Body
Object
content
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
name
string

The name of the license

Example:
Trial License
description
string

The description of the license

Example:
This is free Trial License with limited access to features
life_cycle_state
string

The life cycle state of the license

Enumeration:
ACTIVE
INACTIVE
assets
Array

The assets of a license

Object
id
string GUID

The asset identifier

Example:
1a7fc6dc-9932-5965-b028-14843782c843
name
string

The name of the asset

Example:
CRM
description
string

The description of the asset

Example:
Asset for CRM modules
modules
Array

The modules of the asset

Object
name
string

The name of the module

Example:
Contacts
features
Array

The features of the module

Object
name
string

The name of the feature

Example:
View Contacts
license_code
string

The license code of the feature

Example:
CRM_CON_VIEW
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/organization/d332dd8a-254e-47c9-ba1f-3f369877a9b3/licenses/42f3752c-676a-8245-1c87-130b93f960c7 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": {
        "id": "42f3752c-676a-8245-1c87-130b93f960c7",
        "name": "Trial License",
        "description": "The is a Trial License with limited access to features",
        "life_cycle_state": "ACTIVE",
        "assets": [
            {
                "id": "1a7fc6dc-9932-5965-b028-14843782c843",
                "name": "CRM",
                "description": "Asset for CRM modules",
                "modules": [
                    {
                        "name": "Contacts",
                        "features": [
                            {
                                "name": "View Contacts",
                                "license_code": "CRM_CON_VIEW"
                            },
                            {
                                "name": "Manage Contacts",
                                "license_code": "CRM_CON_MANAGE"
                            }
                        ]
                    },
                    {
                        "name": "Activities",
                        "features": [
                            {
                                "name": "View Activities",
                                "license_code": "CRM_ACT_VIEW"
                            },
                            {
                                "name": "Manage Activities",
                                "license_code": "CRM_ACT_MANAGE"
                            }
                        ]
                    }
                ]
            },
            {
                "id": "a744fded-8f08-0dd9-97ef-8a97c5512c38",
                "name": "Analytics",
                "description": "Asset for Analytics modules",
                "modules": [
                    {
                        "name": "Insights",
                        "features": [
                            {
                                "name": "View Insights",
                                "license_code": "ANA_INS_VIEW"
                            },
                            {
                                "name": "Manage Insights",
                                "license_code": "ANA_INS_MANAGE"
                            }
                        ]
                    },
                    {
                        "name": "Reports",
                        "features": [
                            {
                                "name": "View Reports",
                                "license_code": "ANA_REP_VIEW"
                            },
                            {
                                "name": "Manage Reports",
                                "license_code": "ANA_REP_MANAGE"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Perform License Actions
POST /licenses/{id}/actions

Perform an action on an existing license

Path variables

id
string GUID required

The license (identifier) whose life cycle state will be updated

Example:
42f3752c-676a-8245-1c87-130b93f960c7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
life_cycle_state
string

The life cycle state that the license will changed into

Enumeration:
ACTIVE
INACTIVE

Responses

200 OK

Successfull Requst

Body
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/licenses/42f3752c-676a-8245-1c87-130b93f960c7/actions HTTP/1.1 

Content-Type: application/json

{
    "life_cycle_state": "ACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42f3752c-676a-8245-1c87-130b93f960c7"
}
Add Assets to License
POST /licenses/{id}/assets

Add assets to license

Path variables

id
string GUID required

The license (identifier) for which assets will be set

Example:
42f3752c-676a-8245-1c87-130b93f960c7

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
assets
Array

The assets added to the license

Object
id
string

The asset identifier to add to the license

Example:
"2b7adb86-ef99-a693-699f-ca2f48b75b91"

Responses

200 OK

Successful Request

Body
Object
id
string GUID

The license identifier

Example:
42f3752c-676a-8245-1c87-130b93f960c7
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/licenses/42f3752c-676a-8245-1c87-130b93f960c7/assets HTTP/1.1 

Content-Type: application/json

{
    "assets": [
        {
            "id": "2b7adb86-ef99-a693-699f-ca2f48b75b91"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42f3752c-676a-8245-1c87-130b93f960c7"
}
Create Asset
POST /assets

Create an asset

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the asset

Example:
CRM
description
string

The description of the asset

Example:
The CRM related modules of the system
modules
Array

The modules of the asset

Object
name
string

The name of the module

Example:
Contacts
features
Array

The features of the module

Object
name
string

The name of the feature

Example:
Manage Contacts
license_code
string

The unique license code of the feature

Example:
CRM_COM_MANAGE

Responses

200 OK

Successsful Request

Body
Object
id
string GUID

The asset identifier

Example:
92357407-15a3-4228-6581-383ffc5c9a74
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/assets HTTP/1.1 

Content-Type: application/json

{
    "name": "CRM",
    "description": "The CRM related modules of the system",
    "modules": [
        {
            "name": "Contacts",
            "features": [
                {
                    "name": "Manage Contacts",
                    "license_code": "CRM_COM_MANAGE"
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "92357407-15a3-4228-6581-383ffc5c9a74"
}
List Assets
GET /assets

Returns a list of assets

Request parameters

search_value
string optional

Search for assets based on name and description

Example:
CRM
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The asset identifier

Example:
81c3f16b-9d36-3eef-6fc3-f9206f2edc6c
name
string

The name of the asset

Example:
CRM
description
string

The description of the asset

Example:
The asset related the CRM modules of the system
modules
Array

The modules of the asset

Object
name
string

The name of the module

Example:
Contacts
features
Array

The features of the module

Object
name
string

The name of the feature

Example:
Manage Contacts
license_code
string

The license code of the feature

Example:
CRM_CON_MANAGE
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/assets HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "81c3f16b-9d36-3eef-6fc3-f9206f2edc6c",
            "name": "CRM",
            "description": "The asset related the CRM modules of the system",
            "modules": [
                {
                    "name": "Contacts",
                    "features": [
                        {
                            "name": "Manage Contacts",
                            "license_code": "CRM_CON_MANAGE"
                        }
                    ]
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Asset
GET /assets/{id}

Returns the details of a single asset

Path variables

id
string GUID required

The asset (identifier) for which information will be retrieved

Example:
addd8657-b32a-fa54-b7d8-3ba166f37779

Responses

200 OK
Body
Object
id
string

The asset identifier

Example:
addd8657-b32a-fa54-b7d8-3ba166f37779
name
string

The name of the asset

Example:
CRM
description
string

The description of the asset

Example:
The asset related to CRM modules
modules
Array

The modules of the asset

Object
name
string

The name of the module

Example:
Contacts
features
Array

The features of the module

Object
name
string

The name of the feature

Example:
View Contacts
license_code
string

The license code of the feature

Example:
CRM_CON_VIEW
Example 1
GET https://sandbox.crm.com/backoffice/v1/assets/addd8657-b32a-fa54-b7d8-3ba166f37779 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "addd8657-b32a-fa54-b7d8-3ba166f37779",
    "name": "CRM",
    "description": "The asset related to CRM modules",
    "modules": [
        {
            "name": "Contacts",
            "features": [
                {
                    "name": "View Contacts",
                    "license_code": "CRM_CON_VIEW"
                }
            ]
        },
        {
            "name": "Activities",
            "features": [
                {
                    "name": "View Activities",
                    "license_code": "CRM_ACT_VIEW"
                }
            ]
        }
    ]
}
Update Asset
PUT /assets/{id}

Update an asset

Path variables

id
string GUID required

The asset (identifier) which will be updated

Example:
92357407-15a3-4228-6581-383ffc5c9a74

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the asset

Example:
CRM
description
string

The description of the asset

Example:
The CRM related modules of the system
modules
Array

The modules of the asset

Object
name
string

The name of the module

Example:
Contacts
features
Array

The features of the module

Object
name
string

The name of the feature

Example:
Manage Contacts
license_code
string

The unique license code of the feature

Example:
CRM_COM_MANAGE

Responses

200 OK

Successsful Request

Body
Object
id
string GUID

The asset identifier

Example:
92357407-15a3-4228-6581-383ffc5c9a74
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/assets/92357407-15a3-4228-6581-383ffc5c9a74 HTTP/1.1 

Content-Type: application/json

{
    "name": "CRM",
    "description": "The CRM related modules of the system",
    "modules": [
        {
            "name": "Contacts",
            "features": [
                {
                    "name": "Manage Contacts",
                    "license_code": "CRM_COM_MANAGE"
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "92357407-15a3-4228-6581-383ffc5c9a74"
}
Delete Asset
DELETE /assets/{id}

Delete a single asset

Path variables

id
string GUID required

The asset (identifier) that will be deleted

Example:
1c64097c-1f09-82d3-5d5e-2f662a254a3d

Responses

200 OK

Successfull Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/assets/1c64097c-1f09-82d3-5d5e-2f662a254a3d HTTP/1.1 

HTTP/1.1 200 OK 
Measurement Units
POST /measurement_units
GET /measurement_units
PUT /measurement_units/{id}
DELETE /measurement_units/{id}
Create Measurement Unit
POST /measurement_units

Create a new measurement unit. A single measurement unit can be created per Web API call.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the measurement unit which is mandatory and unique.

Example:
Phone calls
display_name
string required

The name of the unit that wll be used for display and checkout purposes.

Example:
minutes
description
string

The measurement unit description.

Example:
Unit that measures the duration of a phone call in minutes

Responses

201 Created
Body
Object
id
string

The unique identifier of the new measurement unit

Example:
3ac0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/measurement_units HTTP/1.1 

Content-Type: application/json

{
    "name": "Phone calls",
    "display_name": "minutes",
    "description": "Unit that measures the duration of a phone call in minutes"
}
List Measurement Units
GET /measurement_units

Returns a list of measurement units

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for measurement units using their name or display name.

Example:
GB

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The unique identifier of the measurement unit

Example:
3FD9C84FA60F9FE407140E20F707726A
name
string

The name of measurement unit

Example:
Minutes
display_name
string

The display name of the measurement unit

Example:
min.
description
string

The measurement unit’s description

Example:
Phone call minutes
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/measurement_units HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3FD9C84FA60F9FE407140E20F707726A",
            "name": "Minutes",
            "display_name": "min.",
            "description": "Phone call minutes"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Update Measurement Unit
PUT /measurement_units/{id}

Update an existing unit of measurement. A sinly measurement unit can be updated per Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the measurement unit

Example:
Phone call minutes
display_name
string nullable

The display name of the measurement unit

Example:
minutes
description
string nullable

The measurement unit’s description

Example:
Measures a phone call's duration in minutes

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated measurement unit

Example:
2dc0809f-ed91-4b68-b912-5bd6064d901e
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/measurement_units/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "Phone call minutes",
    "display_name": "minutes",
    "description": "Measures a phone call's duration in minutes"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "2dc0809f-ed91-4b68-b912-5bd6064d901e"
}
Delete Measurement Unit
DELETE /measurement_units/{id}

Deletes an existing unit of measurement. A single measurement unit can be deleted per Web API call

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/measurement_units/{id} HTTP/1.1 

HTTP/1.1 200 OK 
Orders
PUT /order_settings
GET /order_settings
Update Order Settings
PUT /order_settings

Retrieve Order generic settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
numbering_schemes
Array
Object
entity
string
Example:
ORDERS
prefix
string
starting_number
string
number_of_digits
integer
Example:
1
financial_settings
Array nullable
Object
supply_method
string required

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
invoice_type_id
string GUID nullable

The invoice type identifier that will be used. If not specified, then the default invoice type will be used

Example:
4ea25d61-ebfe-3a7b-2a45-96d8b059d369
credit_note_type_id
string GUID nullable

The credit note type identifier that will be used. If not specified, then the default credit note type will be used

Example:
4ea25d61-ebfe-3a7b-2a45-96d8b059d369
milestone_settings
Object

Business rules that define how Invoices will be generated for milestone-based Orders

invoice_type_id
string GUID

The invoice type identifier that will be used. If not specified, then the default invoice type will be used

Example:
3aa25d61-ebfe-3a7b-2a45-96d8b059d369
product_id
string GUID required

The invoice milestone product, i.e. the product that will be included in the milestone invoice. Only products classified as expenses can be specified.

Example:
1aa25d61-ebfe-3a7b-2a45-96d8b059d369

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/order_settings HTTP/1.1 

Content-Type: application/json

{
    "numbering_schemes": [
        {
            "entity": "ORDERS",
            "prefix": "",
            "starting_number": "",
            "number_of_digits": 1
        }
    ],
    "financial_settings": [
        {
            "supply_method": "DELIVERY",
            "invoice_type_id": "4ea25d61-ebfe-3a7b-2a45-96d8b059d369",
            "credit_note_type_id": "4ea25d61-ebfe-3a7b-2a45-96d8b059d369"
        }
    ],
    "milestone_settings": {
        "invoice_type_id": "3aa25d61-ebfe-3a7b-2a45-96d8b059d369",
        "product_id": "1aa25d61-ebfe-3a7b-2a45-96d8b059d369"
    }
}

HTTP/1.1 200 OK 
Get Order Settings
GET /order_settings

Retrieve Order generic settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
numbering_schemes
Object

The type of the event

entity
string required

The entity for which the numbering scheme is configured

Enumeration:
INVOICES
CREDIT_NOTES
PAYMENTS
REFUNDS
ORDERS
SERVICE_REQUESTS
Example:
SERVICE_REQUESTS
prefix
string

The prefix of the numbering scheme. Defaults to the first letter(s) of the entity’s name

Example:
SR
starting_number
string

The starting number of the nuberig scheme (excluding prefix). Defaults to 10001

Default:
10001
Example:
0000001
number_of_digits
string

Number of digits (excluding prefix). Defaults to 5

Default:
5
Example:
7
last_number
string

The last number generated for this numbering scheme

Example:
SR000001
financial_settings
Array

Business rules that define how financial transactions will be issued for Orders

Object
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
invoice_type
Object

Details about the invoice type that will be used

id
string GUID

The invoice type identifier

Example:
The invoice type identifier that will be used
name
string

The invoice type name

Example:
Order Invoice
credit_note_type
Object

Details about the credit note type that will be used

id
string GUID

The credit note type identifier

Example:
a4b059a3-2aa7-b2c2-4191-a966168e97d7
name
string

The credit note type name

Example:
ORDER Credit Note
milestone_settings
Object

Business rules that define how Invoices will be generated for milestone-based Orders

invoice_type
Object

The Invoice type that will be used for milestone invoices

id
string

The unique identifier of the invoice type

Example:
34b059a3-2aa7-b2c2-4191-a966168e97d7
name
string

the invoice type name

Example:
Milestone Invoice
product
Object

Details about a product

id
string GUID

The product identifier

Example:
a0f79973-d4b3-db89-4276-cb4abcccd842
sku
string

The product SKU code

Example:
STB
name
string

The product name

Example:
Set-top-box
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "numbering_schemes": {
        "entity": "SERVICE_REQUESTS", 
        "prefix": "SR",
        "starting_number": "0000001",
        "number_of_digits": "7",
        "last_number": "SR000001"
    },
    "financial_settings": [
        {
            "supply_method": "DELIVERY",
            "invoice_type": {
                "id": "The invoice type identifier that will be used",
                "name": "Order Invoice"
            },
            "credit_note_type": {
                "id": "a4b059a3-2aa7-b2c2-4191-a966168e97d7",
                "name": "ORDER Credit Note"
            }
        }
    ],
    "milestone_settings": {
        "invoice_type": {
            "id": "34b059a3-2aa7-b2c2-4191-a966168e97d7",
            "name": "Milestone Invoice"
        },
        "product": {
            "id": "e283a863-18e1-7cae-48c4-7433bf28cf97",
            "sku": "ABC-12345",
            "name": "A product"
        }
    }
}
Cancellation Reasons
GET /order_cancellation_reasons
POST /order_cancellation_reasons/
PUT /order_cancellation_reasons/{id}
DELETE /order_cancellation_reasons/{id}
List Order Cancellation Reasons
GET /order_cancellation_reasons

Retrieve all reasons that will justify an order cancellation

Request parameters

search_value
string optional

Search for a cancellation reason based on its name or description

Example:
Placed by mistake
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUId

The cancellation reason identifier

Example:
caf332bc-4e90-47b5-a05d-142b264897b9
name
string

The cancellation reason name

Example:
Cancelled by Customer
description
string

The cancellation reason description

Example:
Customer requested to cancel an order due to mistake
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://sandbox.crm.com/backoffice/v1/order_cancellation_reasons HTTP/1.1 

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "caf332bc-4e90-47b5-a05d-142b264897b9",
            "name": "Cancelled by Customer",
            "description": "Customer requested to cancel an order due to mistake"
        },
        {
            "id": "6a628f20-21b6-cb1f-4a9f-c15780c4b7e7",
            "name": "Cancelled by Admin",
            "description": "Order cancelled by admin user"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Create Order Cancellation Reason
POST /order_cancellation_reasons/

Creates a new Cancellation Reason that will be used when cancelling orders

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
description
string

Responses

201 Created
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/order_cancellation_reasons/ HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": ""
}
Update Order Cancellation Reason
PUT /order_cancellation_reasons/{id}

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
description
string

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/order_cancellation_reasons/3423423423 HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": ""
}
Delete Order Cancellation Reason
DELETE /order_cancellation_reasons/{id}

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/order_cancellation_reasons/{id} HTTP/1.1 

HTTP/1.1 200 OK 
Queues
POST /order_queues
PUT /order_queues/{id}
DELETE /order_queues/{id}
GET /order_queues
GET /order_queues/{id}
PUT /queues/{id}/point_of_no_return
GET /order_queue_statuses
Create Order Queue
POST /order_queues

Creates a new Order Queue

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
Example:
Support Calls
description
string
Example:
Deals with support calls
state
string
Enumeration:
ACTIVE
INACTIVE
Default:
ACTIVE
is_upfront
boolean

Determines whether the Order will be invoiced upfront, i.e. on placing the Order and setting its state to New

Default:
false
Example:
true
statuses
Array
Object
order
integer
name
string
Example:
Awaiting customer
description
string
Example:
This status is awaiting confirmation from a customer
colour
string
Example:
F1SJ86
invoice_milestone
Object
percentage
number nullable

Responses

201 Created
Body
Object
id
string

Identifier of the new Order

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/order_queues HTTP/1.1 

Content-Type: application/json

{
    "name": "Support Calls",
    "description": "Deals with support calls",
    "state": "ACTIVE",
    "is_upfront": "true",
    "statuses": [
        {
            "order": 1,
            "name": "Awaiting customer",
            "description": "This status is awaiting confirmation from a customer",
            "colour": "F1SJ86",
            "invoice_milestone": {
                "percentage": 1
            }
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": ""
}
Update Order Queue
PUT /order_queues/{id}

Updates an existing Order Queue

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
description
string
state
string
Enumeration:
ACTIVE
INACTIVE
is_upfront
boolean

Detemrines if Orders of this queue will be invoiced upfront i.e. on placing them and setting their state into New

Example:
true
statuses
Array
Object
order
integer
Example:
1
name
string
Example:
Awaiting customer
description
string
Example:
This status is awaiting confirmation from a customer
colour
string
Example:
F1SJ86
invoice_milestone
Object
percentage
number

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/order_queues/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "state": "ACTIVE",
    "is_upfront": "true",
    "statuses": [
        {
            "order": 1,
            "name": "Awaiting customer",
            "description": "This status is awaiting confirmation from a customer",
            "colour": "F1SJ86",
            "invoice_milestone": {
                "percentage": 1
            }
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Order Queue
DELETE /order_queues/{id}

Deletes an Order Queue

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/order_queues/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List Order Queues
GET /order_queues

Returns a list of Order Queues

Request parameters

search_value
string optional

Search Queues by name, description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
state
string optional

The state of the order queue

Enumeration:
ACTIVE
INACTIVE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
Example:
74D9C84FA60F9FE407140E20F707726A
name
string
Example:
Basic food ordering queue
description
string
state
string
Enumeration:
ACTIVE
INACTIVE
number_of_statuses
integer
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_queues HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "74D9C84FA60F9FE407140E20F707726A",
            "name": "Basic food ordering queue",
            "description": "",
            "state": "ACTIVE",
            "number_of_statuses": 1
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Order Queue
GET /order_queues/{id}

Returns detailed information of an Order Queue

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
Example:
74D9C84FA60F9FE407140E20F707726A
name
string
Example:
Basic food ordering queue
description
string
state
string
Example:
ACTIVE
statuses
Array
Object
id
string
Example:
hGSgKJAGKJAGD
order
integer
name
string
Example:
Awaiting customer
description
string
Example:
Awaiting customer lorem ipsulum
life_cycle_state
string

The type of the event

Enumeration:
NEW

Only one status is allowed for the NEW state per queue

IN PROGRESS

Multiple statuses are allowed for the IN PROGRESS state per queue.

COMPLETED

Only one status is allowed for the COMPLETED state per queue

point_of_no_return
boolean

Shows which order queue status also marks the point of no return for Orders

colour
string
Example:
FSD56F
invoice_milestone
Object
percentage
number
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_queues/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "74D9C84FA60F9FE407140E20F707726A",
    "name": "Basic food ordering queue",
    "description": "",
    "state": "ACTIVE",
    "statuses": [
        {
            "id": "hGSgKJAGKJAGD",
            "order": 1,
            "name": "Awaiting customer",
            "description": "Awaiting customer lorem ipsulum",
            "life_cycle_state": "NEW",
            "point_of_no_return": true,
            "colour": "FSD56F",
            "invoice_milestone": {
                "percentage": 1
            }
        }
    ]
}
Set Point of No return
PUT /queues/{id}/point_of_no_return

Set the point of no return to a status in a queue

Path variables

id
string required

The unique identified of the order queue

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

Shows how point of no return is managed through the Web API call

Enumeration:
ADD
REMOVE
Default:
ADD
Example:
ADD
status_id
string

The unique identifier of the queue status. Must be one of the non-deleted statuses of the specified queue. Required when setting/changing the point of no return as it shows which status is considered as the point of no return for orders of this queue

Example:
5dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/queues/{id}/point_of_no_return HTTP/1.1 

Content-Type: application/json

{
    "action": "ADD",
    "status_id": "5dc0809f-ed91-4b68-b912-5bd6064d901e"
}

HTTP/1.1 200 OK 
List Order Queue Statuses
GET /order_queue_statuses

Returns a list of Order Queues

Request parameters

name
string optional
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
Example:
56923c81-275b-fd53-7bb7-a9d6001db8db
name
string
Example:
Basic food ordering queue
queue
Object
id
string
Example:
56923c81-275b-fd53-7bb7-a9d6001db8db
name
string
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_queue_statuses HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "56923c81-275b-fd53-7bb7-a9d6001db8db",
            "name": "Basic food ordering queue",
            "queue": {
                "id": "56923c81-275b-fd53-7bb7-a9d6001db8db",
                "name": ""
            }
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Categories
POST /order_categories
DELETE /order_categories/{id}
PUT /order_categories/{id}
GET /order_categories
Create Order Category
POST /order_categories

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
descripion
string
parent_id
string

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/order_categories HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "descripion": "",
    "parent_id": ""
}
Delete Order Category
DELETE /order_categories/{id}

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

200 OK

The request has succeeded

Example 1
DELETE https://devapi.crm.com/backoffice/v1/order_categories/{id} HTTP/1.1 

HTTP/1.1 200 OK 
Update Order Category
PUT /order_categories/{id}

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
description
string
parent_id
string

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/order_categories/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "parent_id": ""
}
List Order Categories
GET /order_categories

Returns a list of Order Categories

Request parameters

parent_id
string optional
name
string optional
return_all
boolean optional
search_value
string optional

Search for a category using its name or description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
name
string
description
string
child_nodes
integer
Example:
2
parent
Object
id
string
name
string
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://stagingapi.crm.com/backoffice/v1/order_categories HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "name": "",
            "description": "",
            "child_nodes": 2,
            "parent": {
                "id": "",
                "name": ""
            }
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Fulfillment Policies
POST /order_fulfillment_policies/
PUT /order_fulfillment_policies/{id}
DELETE /order_fulfillment_policies/{id}
GET /order_fulfillment_policies
GET /order_fulfillment_policies/{id}
GET /supply_methods
Create Order Fulfillment Policy
POST /order_fulfillment_policies/

Creates an Order Fulfillment Policy

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
description
string
supply_methods
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
minimum_amount
number
automatic_completion
Object
automatic_completion_time
string
Example:
30
automatic_completion_time_UOT
string
Example:
MINUTES
expiration_settings
Object
type
string
Example:
NEVER_EXPIRES
expires_in
integer
Example:
3
expiration_UOT
string
Example:
DAYS
completion_time_applicable
boolean

Defines whether order completion time is appicable

Example:
true
average_completion_time
Object
time_to_complete
integer
Example:
30
time_to_complete_UOT
string
Example:
MINUTES
expenses
Array
Object
supply_method
string
Example:
DELIVERY
product_id
string
order_amount
number

Defines the maximum threshold for applying the expense on the order (i.e. apply 2 euro delivery expense for orders less than 10 euros)

Example:
10
accessibility
Object

Defines whether the fulfillment policy is applicable for all organisations under the Business or specific organisations

type
string
Enumeration:
ALL
SPECIFIC
Default:
ALL
organisations
Array of string

The organisations (Merchants, Venues) that will fulfill orders based on this policy (applicable only if type = SPECIFIC)

Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
payment_method_types
Array

The applicable payment method types for this policy. If not specified then all allowed payment method types are applicable.

string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The fulfillment policy identifier

Example:
d892c9b4-0a6b-baf9-8a32-913c932bd2ab
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/order_fulfillment_policies/ HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "supply_methods": "DELIVERY",
    "minimum_amount": 1,
    "automatic_completion": {
        "automatic_completion_time": "30",
        "automatic_completion_time_UOT": "MINUTES"
    },
    "expiration_settings": {
        "type": "NEVER_EXPIRES",
        "expires_in": 3,
        "expiration_UOT": "DAYS"
    },
    "completion_time_applicable": "true",
    "average_completion_time": {
        "time_to_complete": 30,
        "time_to_complete_UOT": "MINUTES"
    },
    "expenses": [
        {
            "supply_method": "DELIVERY",
            "product_id": "",
            "order_amount": 10
        }
    ],
    "accessibility": {
        "type": "ALL",
        "organisations": [
            ""
        ]
    },
    "payment_method_types": [
        "CARD"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "d892c9b4-0a6b-baf9-8a32-913c932bd2ab"
}
Update Order Fulfillment Policy
PUT /order_fulfillment_policies/{id}

Path variables

id
string GUID required

The order fulfillment policy that will be updated

Example:
d892c9b4-0a6b-baf9-8a32-913c932bd2ab

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
description
string
supply_methods
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
minimum_amount
integer
Example:
1
automatic_completion
Object
automatic_completion_time
string
Example:
30
automatic_completion_time_UOT
string
Example:
MINUTES
expiration_settings
Object
type
string
Example:
NEVER_EXPIRES
expires_in
integer
Example:
3
expiration_UOT
string
Example:
DAYS
completion_time_applicable
boolean

Defines whether order completion time is appicable

Example:
true
average_completion_time
Object
time_to_complete
integer
Example:
30
time_to_complete_UOT
string
Example:
MINUTES
expenses
Array
Object
supply_method
string
Example:
DELIVERY
product
Object
id
string
sku
string
order_amount
number

Defines the maximum threshold for applying the expense on the order (i.e. apply 2 euro delivery expense for orders less than 10 euros)

accessibility
Object

Defines whether the fulfillment policy is applicable for all organisations under the Business or specific organisations

type
string
Enumeration:
ALL
SPECIFIC
Default:
ALL
organisations
Array of string

The organisations (Merchants, Venues) that will fulfill orders based on this policy (applicable only if type = SPECIFIC)

Example:
[
    "CAD1E31269B76D7A65ACCE45B2E68DFD"
]
payment_method_types
Array

The applicable payment method types for this policy. If not specified then all allowed payment method types are applicable.

string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE

Responses

200 OK

The request has succeeded

Body
Object
id
string GUID

The order fulfillment policy identifier

Example:
d892c9b4-0a6b-baf9-8a32-913c932bd2ab
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/order_fulfillment_policies/d892c9b4-0a6b-baf9-8a32-913c932bd2ab HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "supply_methods": "DELIVERY",
    "minimum_amount": 1,
    "automatic_completion": {
        "automatic_completion_time": "30",
        "automatic_completion_time_UOT": "MINUTES"
    },
    "expiration_settings": {
        "type": "NEVER_EXPIRES",
        "expires_in": 3,
        "expiration_UOT": "DAYS"
    },
    "completion_time_applicable": "true",
    "average_completion_time": {
        "time_to_complete": 30,
        "time_to_complete_UOT": "MINUTES"
    },
    "expenses": [
        {
            "supply_method": "DELIVERY",
            "product": {
                "id": "",
                "sku": ""
            },
            "order_amount": 1
        }
    ],
    "accessibility": {
        "type": "ALL",
        "organisations": [
            ""
        ]
    },
    "payment_method_types": [
        "CRM_WALLET"
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "d892c9b4-0a6b-baf9-8a32-913c932bd2ab"
}
Delete Order Fulfillment Policy
DELETE /order_fulfillment_policies/{id}

Path variables

id
string GUID required

The order fulfillment poilicy that will be deleted

Example:
d892c9b4-0a6b-baf9-8a32-913c932bd2ab

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/order_fulfillment_policies/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List Order Fulfillement Policies
GET /order_fulfillment_policies

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search by name or description

fulfilled_by
string optional
supply_method
string optional
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
ALL

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
name
string
description
string
supply_methods
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
organisations
Array
Object
id
string
name
string
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_fulfillment_policies HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "name": "",
            "description": "",
            "supply_methods": "PICK_UP",
            "organisations": [
                {
                    "id": "",
                    "name": ""
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Order Fulfillment Policy
GET /order_fulfillment_policies/{id}

Returns detailed information for an Order fulfillment policy

Path variables

id
string GUID required

The order fulfillment policy that will be retrieved

Example:
c011cb43-b76e-7e5a-436c-f5917e358849

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

Body
Object
name
string
description
string
supply_methods
string
Enumeration:
DELIVERY
PICK_UP
DIRECT_SALE
ALL
minimum_amount
number
automatic_completion
Object
automatic_completion_time
string
Example:
30
automatic_completion_time_UOT
string
Example:
MINUTES
currency
string
Example:
EUR
expiration_settings
Object
type
string
Example:
NEVER_EXPIRES
expires_in
integer
Example:
3
expiration_UOT
string
Example:
DAYS
completion_time_applicable
boolean

Defines whether order completion time is appicable

Example:
true
average_completion_time
Object
time_to_complete
integer
Example:
30
time_to_complete_UOT
string
Example:
MINUTES
accessibility
Object

Defines whether the fulfillment policy is applicable for all organisations under the Business or specific organisations

type
string
Enumeration:
ALL
SPECIFIC
organisations
Array

The organisations (Merchants, Venues) that will fulfill orders based on this policy (applicable only if type = SPECIFIC)

Object
id
string

The organisation identifier

name
string

The name of the organisation

payment_method_types
Array

The applicable payment method types for this policy

string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
expenses
Array
Object
supply_method
string
Example:
DELIVERY
product
Object
id
string
sku
string
order_amount
string

Defines the maximum threshold for applying the expense on the order (i.e. apply 2 euro delivery expense for orders less than 10 euros)

Example 1
GET https://sandbox.crm.com/backoffice/v1/order_fulfillment_policies/c011cb43-b76e-7e5a-436c-f5917e358849 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "",
    "description": "",
    "supply_methods": "DELIVERY",
    "minimum_amount": 1,
    "automatic_completion": {
        "automatic_completion_time": "30",
        "automatic_completion_time_UOT": "MINUTES"
    },
    "currency": "EUR",
    "expiration_settings": {
        "type": "NEVER_EXPIRES",
        "expires_in": 3,
        "expiration_UOT": "DAYS"
    },
    "completion_time_applicable": "true",
    "average_completion_time": {
        "time_to_complete": 30,
        "time_to_complete_UOT": "MINUTES"
    },
    "accessibility": {
        "type": "ALL",
        "organisations": [
            {
                "id": "",
                "name": ""
            }
        ]
    },
    "payment_method_types": [
        "CHEQUE"
    ],
    "expenses": [
        {
            "supply_method": "DELIVERY",
            "product": {
                "id": "",
                "sku": ""
            },
            "order_amount": ""
        }
    ]
}
List Supply Methods
GET /supply_methods

Returns supported supply methods based on the fulfillment policies configured

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
supply_methods
Array of string

The supported supply methods

Example:
[
    "DELIVERY","PICK_UP","DIRECT_SALE"
]
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/supply_methods HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "supply_methods": [
        "DELIVERY",
        "PICK_UP"
    ]
}
Completion Rules
GET /order_completion_rules
GET /order_completion_rules/{id}
POST /order_completion_rules
PUT /order_completion_rules/{id}
DELETE /order_completion_rules/{id}
List Order Completion Rules
GET /order_completion_rules

List order cmpletion rules

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
additional_completion_time
integer
Example:
5
additional_completion_time_UOT
string
Example:
MINUTES
min_number_of_running_orders
integer
Example:
5
max_number_of_running_orders
integer
Example:
10
organisation
Object
id
string
name
string
product_conditions
Array
Object
item_type
string
Example:
TYPE
item_id
string
timing_conditions
Array
Object
day_of_week
string
Enumeration:
MONDAY
TUESDAY
start_time
string
Example:
09:00
end_time
string
Example:
11:00
min_number_of_pending_items
integer
max_number_of_pending_items
integer
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
Example 1
GET https://stagingapi.crm.com/backoffice/v1/order_completion_rules HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id": "",
            "additional_completion_time": 5,
            "additional_completion_time_UOT": "MINUTES",
            "min_number_of_running_orders": 5,
            "max_number_of_running_orders": 10,
            "organisation": {
                "id": "",
                "name": ""
            },
            "product_conditions": [
                {
                    "item_type": "TYPE",
                    "item_id": ""
                }
            ],
            "timing_conditions": [
                {
                    "day_of_week": "TUESDAY",
                    "start_time": "09:00",
                    "end_time": "11:00"
                }
            ],
            "min_number_of_pending_items": 1,
            "max_number_of_pending_items": 1
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Order Completion Rule
GET /order_completion_rules/{id}

Get order completion rule

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string
additional_completion_time
integer
Example:
5
additional_completion_time_UOT
string
Example:
MINUTES
min_number_of_running_orders
integer
Example:
5
max_number_of_running_orders
integer
Example:
10
organisation
Object
id
string
name
string
product_conditions
Array
Object
item_type
string
Example:
TYPE
item_id
string
name
string

The name of the product type or the product SKU depending on the condition type

timing_conditions
Array
Object
day_of_week
string
Example:
MONDAY
start_time
string
Example:
09:00
end_time
string
Example:
11:00
min_number_of_pending_items
integer
Example:
1
max_number_of_pending_items
integer
Example:
1
Example 1
GET https://stagingapi.crm.com/backoffice/v1/order_completion_rules/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "additional_completion_time": 5,
    "additional_completion_time_UOT": "MINUTES",
    "min_number_of_running_orders": 5,
    "max_number_of_running_orders": 10,
    "organisation": {
        "id": "",
        "name": ""
    },
    "product_conditions": [
        {
            "item_type": "TYPE",
            "item_id": "",
            "name": ""
        }
    ],
    "timing_conditions": [
        {
            "day_of_week": "MONDAY",
            "start_time": "09:00",
            "end_time": "11:00"
        }
    ],
    "min_number_of_pending_items": 1,
    "max_number_of_pending_items": 1
}
Add Order Completion Rule
POST /order_completion_rules

Creates a new rule for completing orders

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
additional_completion_time
integer
Example:
5
additional_completion_time_UOT
string
Example:
MINUTES
min_number_of_running_orders
integer
Example:
5
max_number_of_running_orders
integer
Example:
10
organisation_id
string
product_conditions
Array
Object
item_type
string
Enumeration:
PRODUCT
TYPE
item_id
string
timing_conditions
Array
Object
day_of_week
string
Example:
MONDAY
start_time
string
Example:
09:00
end_time
string
Example:
11:00
min_number_of_pending_items
integer
max_number_of_pending_items
integer

Responses

201 Created
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://stagingapi.crm.com/backoffice/v1/order_completion_rules HTTP/1.1 

Content-Type: application/json

{
    "additional_completion_time": 5,
    "additional_completion_time_UOT": "MINUTES",
    "min_number_of_running_orders": 5,
    "max_number_of_running_orders": 10,
    "organisation_id": "",
    "product_conditions": [
        {
            "item_type": "PRODUCT", 
            "item_id": ""
        }
    ],
    "timing_conditions": [
        {
            "day_of_week": "MONDAY",
            "start_time": "09:00",
            "end_time": "11:00"
        }
    ],
    "min_number_of_pending_items": 1,
    "max_number_of_pending_items": 1
}
Update Order Completion Rule
PUT /order_completion_rules/{id}

Update a existing rule for completing orders

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
additional_completion_time
integer
Example:
5
additional_completion_time_UOT
string
Example:
MINUTES
min_number_of_running_orders
integer
Example:
5
max_number_of_running_orders
integer
Example:
10
organisation_id
string
product_conditions
Array
Object
item_type
string
Enumeration:
PRODUCT
TYPE
item_id
string
timing_conditions
Array
Object
day_of_week
string
Example:
MONDAY
start_time
string
Example:
09:00
end_time
string
Example:
11:00
min_number_of_pending_items
integer
max_number_of_pending_items
integer

Responses

200 OK
Body
Object
id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://stagingapi.crm.com/backoffice/v1/order_completion_rules/{id} HTTP/1.1 

Content-Type: application/json

{
    "additional_completion_time": 5,
    "additional_completion_time_UOT": "MINUTES",
    "min_number_of_running_orders": 5,
    "max_number_of_running_orders": 10,
    "organisation_id": "",
    "product_conditions": [
        {
            "item_type": "TYPE", 
            "item_id": ""
        }
    ],
    "timing_conditions": [
        {
            "day_of_week": "MONDAY",
            "start_time": "09:00",
            "end_time": "11:00"
        }
    ],
    "min_number_of_pending_items": 1,
    "max_number_of_pending_items": 1
}
Delete Order Completion Rule
DELETE /order_completion_rules/{id}

Delete an existing order completion rule

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://stagingapi.crm.com/backoffice/v1/order_completion_rules/{id} HTTP/1.1 

HTTP/1.1 204 No Content 
Passes

Generic settings for passes

GET /pass_settings
PUT /pass_settings
Get Pass Settings
GET /pass_settings

Get the generic settings for financial passes

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
pass_code_hashing
Object

Pass code hashing details

is_enabled
boolean

Is pass code hashing enabled?

Example:
true
algorithm
string

Hashing algorithm (if hashing is enabled)

Enumeration:
SHA-1
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/pass_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "pass_code_hashing": {
        "is_enabled": "true",
        "algorithm": "SHA-1"
    }
}
Update Pass Settings
PUT /pass_settings

Update generic financial pass settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
pass_code_hashing
Object

Pass code hashing details

is_enabled
boolean

Is pass code hashing enabled?

Example:
true
algorithm
string

Hashing algorithm (if hashing is enabled)

Enumeration:
SHA-1

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/pass_settings HTTP/1.1 

Content-Type: application/json

{
    "pass_code_hashing": {
        "is_enabled": "true",
        "algorithm": "SHA-1"
    }
}
Payment Methods
POST /allowed_payment_methods
GET /allowed_payment_methods
Update Allowed Payment Methods
POST /allowed_payment_methods

Update allowed payment methods for organisations

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
payment_method_type
string

The payment method to update

Enumeration:
JCC_MERCHANT
is_allowed
boolean

Defines whether the payment method is allowed or not. Defaults to False.

Example:
false

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/allowed_payment_methods HTTP/1.1 

Content-Type: application/json

[
    {
        "allowed_payment_method": "PAYPAL",
        "is_allowed": "false"
    }
]
List Allowed Payment Methods
GET /allowed_payment_methods

List allowed payment methods for organisations

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Array
Object
payment_method_type
string

The type of the event

Enumeration:
CARD
ACCOUNT_DEBIT
WALLET
CRM_WALLET
CASH
CHEQUE
label
string

The label of allowed payment method for display purposes

Example:
Cash
is_allowed
string

Defines whether the payment method is allowed or not.

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/allowed_payment_methods HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "payment_method_type": "WALLET",
        "label": "Cash",
        "is_allowed": "true"
    }
]
Platform
PUT /platform_settings
GET /platform_settings
GET /software_languages
Set Platform Settings
PUT /platform_settings

Set generic platform settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
timezone
string nullable

The timezone of the organisation (applicable for Business organisations)

Example:
EUROPE/ATHENS

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/platform_settings HTTP/1.1 

Content-Type: application/json

{
    "timezone": "EUROPE/ATHENS"
}

HTTP/1.1 200 OK 
Get Platform Settings
GET /platform_settings

Get generic platform settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
timezone
string

The organisation timezone

Example:
EUROPE/ATHENS
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/platform_settings HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "timezone": "EUROPE/ATHENS"
}
Get Software Languages
GET /software_languages

Retrieve a list of languages that the back-end software can be translated to

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
language
string

The language code

Example:
EN
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/software_languages HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "language": "EN"
        }
    ]
}
Applications

Managing Application Settings and Publishing

POST /applications
PUT /applications/{id}
DELETE /applications/{id}
GET /applications
GET /applications/{id}
POST /applications/{id}/settings
Create Application
POST /applications

Create a new application

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The application name

Example:
Brew Coffee
description
string nullable

The application description

Example:
Best coffee application
app_type
string

The application type

Enumeration:
NATIVE

Mobile Consumer Applications (Apple and Google)

NATIVE_MERCHANT

Mobile Merchant Applications (Apple and Google)

WEB

Web Portal

CAPTIVE

Captive Portal

Responses

200 200

Successful Request

Body
Object
id
string GUID

The application identifier

Example:
118e64a6-85ad-413a-b6a1-9aeffd678ef3
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/applications HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Brew Coffee",
    "description": "Best coffee application",
    "app_type": "PWA"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "118e64a6-85ad-413a-b6a1-9aeffd678ef3"
}
Update Application
PUT /applications/{id}

Update an existing application

Path variables

id
string GUID required

The application (identifer) that will be updated

Example:
5fd79941-e4ce-e6b9-2a3c-b455e3fb0220

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The application name

Example:
Brew Coffee
description
string nullable

The application description

Example:
Best coffee application

Responses

200 200

Successful Request

Body
Object
id
string GUID

The application identifier

Example:
118e64a6-85ad-413a-b6a1-9aeffd678ef3
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/applications/5fd79941-e4ce-e6b9-2a3c-b455e3fb0220 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Brew Coffee",
    "description": "Best coffee application"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "118e64a6-85ad-413a-b6a1-9aeffd678ef3"
}
Delete Application
DELETE /applications/{id}

Delete an existing application

Path variables

id
string GUID required

The application (identifer) that will be deleted

Example:
eac1f771-2608-85c1-9289-08abb5c1d7a0

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/applications/eac1f771-2608-85c1-9289-08abb5c1d7a0 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Applications
GET /applications

Retrieves a list of all applications

Request parameters

name
string optional

Filters based on application name

Example:
Best Coffee App
type
array of applicationType-Enum optional

Filters based on application type

Collection format: csv
platform_app_id
string optional

The platform application identifier

Example:
f9e4b742-bfe1-09dc-f623-de71aaed61ff
version
string optional

The application version number

Example:
1.1
cloud_name
string optional

Use cloud name to retrieve Web APP settings.

Example:
crm
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successfull Completed

Body
Object
content
Array
Object
id
string GUID

The application identifier

Example:
6d2652b7-9b8d-6174-65c3-c3fefc87e8cd
name
string

The application name

Example:
Coffee App
description
string

The application description

Example:
Best coffee app description
app_type
string

The application type

Enumeration:
NATIVE

Mobile Consumer Applications (Apple and Google)

NATIVE_MERCHANT

Mobile Merchant Applications (Apple and Google)

WEB

Web Portal

CAPTIVE

Captive Portal

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/applications HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "6d2652b7-9b8d-6174-65c3-c3fefc87e8cd",
            "name": "Coffee App",
            "description": "Best coffee app description",
            "app_type": "NATIVE"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Application
GET /applications/{id}

Get details of a single application

Path variables

id
string GUID required

The application (identifer) that will be returned

Example:
bd909bd2-2397-8af8-b256-87e496620209

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successfull Completed

Body
Object
id
string GUID

The application identifier

Example:
0b9ab3de-af32-47f9-faca-ff5c94063819
name
string

The application name

Example:
Brew Coffee App
description
string

The application description

Example:
Best coffee app
app_type
string

The application type

Enumeration:
NATIVE

Mobile Consumer Applications (Apple and Google)

NATIVE_MERCHANT

Mobile Merchant Applications (Apple and Google)

WEB

Web Portal

CAPTIVE

Captive Portal

appearance
Object

Details about the app appearance

background_color
string

The background color that the app will use as the main color (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Example:
#eb4034
card_color
string

The color that te app will use on card-like components (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Example:
#eb4034
button_color
string

The color that the app will use on all buttons, link text, selected tabs (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Default:
#d14b50
Example:
#eb4034
landing_page_colours
Object

Colours applied to the landing page. Note: New colour configurations

background
string

The landing page background colour (hex code), this can be replaced by an image defined in creatives.usage_type = LANDING_PAGE_BACKGROUND_IMAGE

Default:
#6c757d
Example:
#eb4034
button
string

Landing page button colour (hex code)

Default:
#d14b50
Example:
#36e3d7
text
string

Landing page text colour (hex code)

Default:
#ffffff
Example:
#e3cf36
screen_colours
Object

Colours applied to other screens. Note: New colour configurations

button
string

Screen button colour is applied to clickable buttons, selected tabs and text option buttons (hex code)

Default:
#d14b50
Example:
#36e3d7
wallet
string

Colour of the wallet card (hex code). If reward tiering is configured then this colour is overridden with the reward tier colour

Default:
#6c757d
Example:
#eb4034
card
string

Colour used on card like components across all screens (hex code)

Default:
#d14b50
Example:
#eb4034
advanced_colour_mapping
string

JSON script contaning specific mapping of existing colour settings to particular elements of the app. Used in special circumstances to allow fine tuning of colour mapping without the need to rebuild the app. This is maintained solely by CRMI and is not visible on the back-end UI.

Example:
let appearance = { main_color: '#ffffff', //landing_page.text_color, landing_page.button_text_color, main_page.card_text_color, main_page.icon_color, side_bar.text_color, side_bar.icon_color, tab_bar.background_color button_color: '#50e3c2',//landing_page.button_color, main_page.button_color, main_page.button_selected, side_bar.background_color, tab_bar.selected, card_color: '#F0F0F3', //main_page.button_unselected, main_page.card_bg_color, main_page.input_background_color background_color: '#d32166', //landing_page.background_color text_normal_color: '#212121', //main_page.text_label_color, main_page.input_label_color text_main_color: '#03041D', //main_page.button_unselected_text_color, main_page.text_color, main_page.text_title_color, main_page.card_icon_color, main_page.input_text_color border_color: 'rgba(3, 4, 29, 0.16)', //main_page.border_button_color, main_page.border_input_color, tab_bar.unselected, darkmode_color: '#212121', //background pages when dark_mode = true darkmode_text: '#ffffff', //main_page.text_color }
dark_mode
boolean

The colour scheme of the app

Default:
false
text_font
string

The text font style that the app will use

Enumeration:
San Francisco
Roboto
Helvetica
Open Sans
Poppins
Georgia
Gilroy
homepage_layout
string

The homepage layout of the app

Enumeration:
LAYOUT1
LAYOUT2
LAYOUT3
LAYOUT4
LAYOUT5
Default:
LAYOUT1
about_details
Object

Defines the app details (about, terms and conditions, privacy policy)

about
Object

Details about us (URL or contact should be specified)

url
string

The about URL

Example:
https?/crm.com
content
string

The about rich content

Example:
About Us
terms_conditions
Object

Details about the terms and conditions (URL or contact should be specified)

url
string

The terms and conditions URL

Example:
https?/crm.com
content
string

The terms and conditions rich content

Example:
Terms & Conditions
privacy_policy
Object

Details about the privacy policy (URL or contact should be specified)

url
string

The privacy policy URL

Example:
https?/crm.com
content
string

The privacy policy rich content

Example:
Privacy Policy
faqs
Object

Details about the FAQs (URL or contact should be specified)

url
string

The FAQs URL

Example:
https://crm.com
content
string

The FAQs rich content

Example:
FAQs
contact_us
Object

Details about contact us

email_address
string

The contact us email address

Example:
info@crm.com
phone_country_code
string

The contact us phone number country code

Example:
CYP
phone_number
string

The contact us phone number

Example:
22265566
website
string

The contact us website

Example:
https?/crm.com
features
Object

Details about the features that will be supported by the app

billing
boolean required

Defines whether billing feature is supported

Example:
true
rewards
boolean required

Defines whether rewards feature is supported

Example:
true
ordering
boolean required

Defines whether ordering feature is supported

Example:
true
subscriptions
boolean required

Defines whether subscriptions feature is supported

Example:
true
finance
boolean required

Defines whether finance feature is supported

Example:
true
crm
boolean required

Defines whether crm feature is supported

Example:
true
marketing_content
boolean required

Defines whether marketing content feature is supported

Default:
false
Example:
false
business_network
boolean

Defines whether business network feature is supported

Example:
false
business_network_details
Object

Defines the supported business network items (only if business network feature is supported)

multitenancy
boolean

Defines whether multitenancy will be supported

Example:
false
ordering_model
string

Defines the consumer ordering model

Enumeration:
MARKETPLACE
SINGLE_BUSINESS
contact
Object

Supported contact features for app & portal

is_supported
boolean

Are contact features supported?

Example:
true
code_representation
string nullable

How the contact code will be depicted on the app/portal, for scanning purposes

Enumeration:
BARCODE

As a barcode

QR_CODE

As a QR code

Example:
BARCODE
crm_details
Object

Defines the supported crm items

service_requests
boolean

Defines whether contacts will be able to submit service requests

Example:
false
finance_details
Object

Defines the supported finance items (only if finance feature is supported)

wallet_top_up
boolean

Defines whether contacts will be able to top up their wallets

Example:
false
redeem_pass
boolean

Defines whether contacts will be able to redeem a pass

Example:
true
redeem_pass_attributes
Array

Defines whether redeem pass should be supported by other attributes

string

The type of supplementary attribute

Enumeration:
CODE
VALUE
PIN
ordering_details
Object

Defines the supported ordering items (only if ordering feature is supported)

ordering_pickup
boolean

Defines whether pick up is supported as supply method

Example:
true
ordering_delivery
boolean

Defines whether delivery is supported as supply method

Example:
true
ordering_direct_sale
boolean

Defines whether direct sale is supported as supply method

Example:
true
preferred_organisation_orders
boolean

Defines whether contact can set preferred organisation for ordering

Example:
true
ordering_countries
Array

Defines the countries where orders will be applicable

Object
country
string

The country (code)

Example:
CYP
allow_wallet_funds_payment
boolean

Defines whether contact can pay for order using wallet funds

Example:
true
allow_specific_funds_amount
boolean

Defines whether contacts can specific the wallet funds amount to use on orders

Example:
false
allow_full_basket_wallet_fund
boolean

Defines whether the wallet fund amount must cover the full basket amount

Example:
false
order_catalogs
Array

Defines a list of order catalogs that should filter available products to order

Object
id
string GUID

The order catalog identifier

Example:
b948f9ee-e17c-2404-77ba-26e0589d686c
name
string

The order catalog name

Example:
WiFi Products
rewards_details
Object

Defines the supported rewards items (only if rewards feature is supported)

automatic_spends
boolean

Defines whether automatic spend preferences will be supported

Example:
true
automatic_spend_options
Object

Details about the automatic spend settings that a contact can set up

any_purchase
boolean

Defines whether automatic spends can be set for any purchase

Example:
true
any_purchase_collect_on
string

Defines whether contact can set preferred merchants on which automatic spends wil be applied (applicable only if any_purchase = true)

Enumeration:
ANY_MERCHANT

Contact auto spends will be applied on all merchant purchases

PREFERRED_MERCHANT

Contact will have the ability to select the merchants that auto spends will be applied

next_purchase_merchant
boolean

Defines whether automatic spends can be set for next purchase at merchant X

Example:
true
return_cashback
boolean

Defines whether the ability to select payment method for cashback returns will be supported

Example:
true
customer_selfservice_purchases
boolean

Defines whether customer self service purchase identification and OTP request to spend will be supported

Example:
true
reward_tiering
boolean

Defines whether reward tiering will be supported

Example:
false
preferred_organisation_rewards
boolean

Defines whether contact can set preferred organisation for rewards

Example:
true
refer_friend
boolean

Defines whether refer a friend will be supported

Example:
true
refer_friend_communication_method
string

Defines the communication method that should be used for refer a friend

Enumeration:
EMAIL
SMS
otp_spend
boolean

Defines whether OTP send will be supported

Example:
true
otp_spend_attributes
Array

Defines the supplementary attributes that will be supported for OTP spends

string
Example:
AMOUNT
reclaim_purchase_methods
Array

Defines how reclaim purchase identification will be made

string
Enumeration:
BARCODE
TRX_CODE
marketing_content_details
Object

Defines marketing content to display in front-end systems

embedded_links
Array

Define links for embedded browser in front-end systems

Object
title
string

Defines the title of the link

Example:
News & upcoming event
url
string

Defines the url of the link

Example:
https://www.guababeachbar.com/news&events
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
merchant_app
Object

Defines the supported Merchant App items

allow_spend
boolean

Defines whether the merchant app supports submission of Spend requests

Example:
true
restrict_fully_covered
boolean

Defines whether the purchase (front-end reduction) will be posted successfully only if requested spend amount fully covers the purchase amount

Example:
true
auth_support
Object

Details on how customers can auth by the app

email_password
boolean

Supported authentication based on email and password

Example:
true
email_otp
boolean

Supported authentication based on email and one time password

Example:
false
sms_otp
boolean

Supported authentication based on one time password

Example:
true
activate_demo_contact
boolean

Enable to define a demo contact from existing contacts

Example:
true
demo_contact_details
Object

The contact assigned as demo contact

contact_id
string GUID

The id of the contact assigned as demo contact

Example:
BA84F57FC19A4ECB84EE779957364B83
contact_name
string

The name of the contact assigned as demo contact

Example:
John Jones
otp
string

The otp to accept for signing in

Example:
123456
facebook
boolean

Supported authentication based on Facebook

Example:
true
fb_app_id
string

Facebook App ID required for FB authentication

Example:
sfsdf-23-we-wer-3ew-dw
fb_app_secret
string

Facebook App Secret for Server to Server communication (must not be sent to client)

Example:
qqsdf-23-we-wer-3ew-qq
google
boolean

Supported authentication based on Google

Example:
true
google_app_id
string

Google App ID required for Google authentication

Example:
sfsdf-23-we-wer-3ew-dw
google_app_secret
string

Google App Secret for Server to Server communication (must not be sent to client)

Example:
qqsdf-23-we-wer-3ew-qq
change_credentials
boolean

Defines whether contacts will be able to change their authentication details

Example:
false
manage_credentials
Object

Defines whether contacts will be able to manage their authentication details

add_new
boolean

Defiens whether contact will be able to add new authentication details

Example:
true
update_existing
boolean

Defiens whether contact will be able to update existing authentication details

Example:
true
delete_existing
boolean

Defiens whether contact will be able to delete existing authentication details

Example:
true
contact
Object

Details on supported contact attributes

profile_details
Array

Lists all supported contact attributes

Object
type
string

The contact attribute

Enumeration:
BIRTHDATE
NAMEDAY
GENDER
is_supported
boolean

Defines if the profile attribute is supported or not

Example:
true
app_identifiers
Array

Details about the application identifiers per supported platform

Object
platform
string

The platform on which the application will be published

Enumeration:
APPLE
GOOGLE
WEB
platform_app_id
string

The application id of each platform

Example:
1762e052-4805-73eb-36f2-e77d6dc883e8
cloud_name
string

DNS Cloud name for the Web URL

Example:
crmdotcom
version
string

The application version

Example:
1.1
background_creative
Object

The image/video/animation that will be displayed in the app landing page

id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
BACKGROUND
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
2159
format
string

The creative format

Example:
jpg, lottie, mp4
url
string

The creative content URL

Example:
https://assets.crm.com/image/background.jpg
pubic_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

height
integer

The transformed creative height

url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/background.jpg
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
Example 1
GET https://sandbox.crm.com/backoffice/v1/applications/bd909bd2-2397-8af8-b256-87e496620209 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "0b9ab3de-af32-47f9-faca-ff5c94063819",
    "name": "Brew Coffee App",
    "description": "Best coffee app",
    "app_type": "CAPTIVE",
    "appearance": {
        "background_color": "#eb4034",
        "card_color": "#eb4034",
        "button_color": "#eb4034",
        "landing_page_colours": {
            "background": "#eb4034",
            "button": "#36e3d7",
            "text": "#e3cf36"
        },
        "screen_colours": {
            "button": "#36e3d7",
            "wallet": "#eb4034",
            "card": "#eb4034"
        },
        "advanced_colour_mapping": "let appearance = { main_color: '#ffffff', //landing_page.text_color, landing_page.button_text_color, main_page.card_text_color, main_page.icon_color, side_bar.text_color, side_bar.icon_color, tab_bar.background_color button_color: '#50e3c2',//landing_page.button_color, main_page.button_color, main_page.button_selected, side_bar.background_color, tab_bar.selected, card_color: '#F0F0F3', //main_page.button_unselected, main_page.card_bg_color, main_page.input_background_color background_color: '#d32166', //landing_page.background_color text_normal_color: '#212121', //main_page.text_label_color, main_page.input_label_color text_main_color: '#03041D', //main_page.button_unselected_text_color, main_page.text_color, main_page.text_title_color, main_page.card_icon_color, main_page.input_text_color border_color: 'rgba(3, 4, 29, 0.16)', //main_page.border_button_color, main_page.border_input_color, tab_bar.unselected, darkmode_color: '#212121', //background pages when dark_mode = true darkmode_text: '#ffffff', //main_page.text_color }",
        "dark_mode": "false",
        "text_font": "Helvetica",
        "homepage_layout": "LAYOUT1"
    },
    "about_details": {
        "about": {
            "url": "https?/crm.com",
            "content": "About Us"
        },
        "terms_conditions": {
            "url": "https?/crm.com",
            "content": "Terms & Conditions"
        },
        "privacy_policy": {
            "url": "https?/crm.com",
            "content": "Privacy Policy"
        },
        "faqs": {
            "url": "https://crm.com",
            "content": "FAQs"
        },
        "contact_us": {
            "email_address": "info@crm.com",
            "phone_country_code": "CYP",
            "phone_number": "22265566",
            "website": "https?/crm.com"
        }
    },
    "features": {
        "billing": true,
        "rewards": true,
        "ordering": true,
        "subscriptions": "true",
        "finance": "true",
        "crm": "true",
        "marketing_content": "false",
        "business_network": "false",
        "business_network_details": {
            "multitenancy": "false",
            "ordering_model": "MARKETPLACE"
        },
        "contact": {
            "is_supported": "true",
            "code_representation": "BARCODE"
        },
        "crm_details": {
            "service_requests": "false"
        },
        "finance_details": {
            "wallet_top_up": "false",
            "redeem_pass": "true",
            "redeem_pass_attributes": [
                "VALUE"
            ]
        },
        "ordering_details": {
            "ordering_pickup": true,
            "ordering_delivery": true,
            "ordering_direct_sale": "true",
            "preferred_organisation_orders": "true",
            "ordering_countries": [
                {
                    "country": "CYP"
                }
            ],
            "allow_wallet_funds_payment": "true",
            "allow_specific_funds_amount": "false",
            "allow_full_basket_wallet_fund": "false",
            "order_catalogs": [
                {
                    "id": "b948f9ee-e17c-2404-77ba-26e0589d686c",
                    "name": "WiFi Products"
                }
            ]
        },
        "rewards_details": {
            "automatic_spends": true,
            "automatic_spend_options": {
                "any_purchase": "true",
                "any_purchase_collect_on": "ANY_MERCHANT",
                "next_purchase_merchant": "true"
            },
            "return_cashback": true,
            "customer_selfservice_purchases": true,
            "reward_tiering": "false",
            "preferred_organisation_rewards": "true",
            "refer_friend": "true",
            "refer_friend_communication_method": "EMAIL",
            "otp_spend": "true",
            "otp_spend_attributes": [
                "AMOUNT"
            ],
            "reclaim_purchase_methods": [
                "BARCODE"
            ]
        },
        "marketing_content_details": {
            "embedded_links": [
                {
                    "title": "News & upcoming event",
                    "url": "https://www.guababeachbar.com/news&events",
                    "creatives": [
                        {
                            "id": "CA123456789AQWSXZAQWS1236547896541",
                            "usage_type": "LANDING_PAGE_HEADER_IMAGE",
                            "width": 2159,
                            "height": 3075,
                            "format": "jpg",
                            "url": "https://assets.crm.com/image/logo.jpg",
                            "public_id": "crm-com/image",
                            "media": [
                                {
                                    "width": 200,
                                    "height": 300,
                                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "merchant_app": {
            "allow_spend": true,
            "restrict_fully_covered": "true"
        }
    },
    "auth_support": {
        "email_password": true,
        "email_verification": "true",
        "email_otp": "false",
        "sms_otp": true,
        "activate_demo_contact": "true",
        "demo_contact_details": {
            "contact_id": "BA84F57FC19A4ECB84EE779957364B83",
            "contact_name": "John Jones",
            "otp": "123456"
        },
        "facebook": true,
        "fb_app_id": "sfsdf-23-we-wer-3ew-dw",
        "fb_app_secret": "qqsdf-23-we-wer-3ew-qq",
        "google": true,
        "google_app_id": "sfsdf-23-we-wer-3ew-dw",
        "google_app_secret": "qqsdf-23-we-wer-3ew-qq"
    },
    "contact": {
        "profile_details": [
            {
                "type": "NAMEDAY",
                "is_supported": true
            }
        ]
    },
    "app_identifiers": [
        {
            "platform": "GOOGLE",
            "platform_app_id": "1762e052-4805-73eb-36f2-e77d6dc883e8",
            "cloud_name": "crmdotcom",
            "version": "1.1"
        }
    ],
    "background_creative": {
        "id": "CA123456789AQWSXZAQWS1236547896541",
        "usage_type": "BACKGROUND",
        "width": 2159,
        "height": 2159,
        "format": "jpg, lottie, mp4",
        "url": "https://assets.crm.com/image/background.jpg",
        "pubic_id": "crm-com/image",
        "media": [
            {
                "width": 1,
                "height": 1,
                "url": "https://asset.crm.com/image/offer/c_scale,w_200/background.jpg"
            }
        ]
    },
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "APPLE_LOCKSCREEN_ICON",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Set Application Settings
POST /applications/{id}/settings

Set the configuration details (appearance, supported features) of a single application

Path variables

id
string GUID required

The application (identifer) whose settings will be updated

Example:
f8343fdf-a91f-1def-a265-35ac78b0a3ba

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
appearance
Object nullable

Details about the app appearance

background_color
string

The background color that the app will use as the main color (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Example:
#eb4034
card_color
string

The color that te app will use on card-like components (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Example:
#eb4034
button_color
string

The color that the app will use on all buttons, link text, selected tabs (hex code). Note: will temporarily co-exist with landing_page_colours & screen_colours for backward compatibility purposes

Default:
#d14b50
Example:
#eb4034
landing_page_colours
Object

Colours applied to the landing page

background
string

The landing page background colour (hex code), this can be replaced by an image defined in creatives.usage_type = LANDING_PAGE_BACKGROUND_IMAGE

Default:
#6c757d
Example:
#eb4034
button
string

Landing page button colour (hex code)

Default:
#d14b50
Example:
#36e3d7
text
string

Landing page text colour (hex code)

Default:
#ffffff
Example:
#e3cf36
screen_colours
Object

Colours applied to other screens

button
string

Screen button colour is applied to clickable buttons, selected tabs and text button options (hex code)

Default:
#d14b50
Example:
#36e3d7
wallet
string

Colour of the wallet card (hex code). If reward tiering is configured then this colour is overridden with the reward tier colour

Default:
#6c757d
Example:
#eb4034
card
string

Colour used on card like components across all screens (hex code)

Default:
#d14b50
Example:
#eb4034
advanced_colour_mapping
string

JSON script contaning specific mapping of existing colour settings to particular elements of the app. Used in special circumstances to allow fine tuning of colour mapping without the need to rebuild the app. This is maintatined solely via this API call and is not visible on the back-end UI.

Example:
let appearance = { main_color: '#ffffff', //landing_page.text_color, landing_page.button_text_color, main_page.card_text_color, main_page.icon_color, side_bar.text_color, side_bar.icon_color, tab_bar.background_color button_color: '#50e3c2',//landing_page.button_color, main_page.button_color, main_page.button_selected, side_bar.background_color, tab_bar.selected, card_color: '#F0F0F3', //main_page.button_unselected, main_page.card_bg_color, main_page.input_background_color background_color: '#d32166', //landing_page.background_color text_normal_color: '#212121', //main_page.text_label_color, main_page.input_label_color text_main_color: '#03041D', //main_page.button_unselected_text_color, main_page.text_color, main_page.text_title_color, main_page.card_icon_color, main_page.input_text_color border_color: 'rgba(3, 4, 29, 0.16)', //main_page.border_button_color, main_page.border_input_color, tab_bar.unselected, darkmode_color: '#212121', //background pages when dark_mode = true darkmode_text: '#ffffff', //main_page.text_color }
dark_mode
boolean

The colour scheme of the app

Default:
false
text_font
string

The text font style that the app will use

Enumeration:
San Francisco
Roboto
Helvetica
Open Sans
Poppins
Georgia
Gilroy
homepage_layout
string required

The homepage layout of the app

Enumeration:
LAYOUT1
LAYOUT2
LAYOUT3
LAYOUT4
LAYOUT5
Default:
LAYOUT1
about_details
Object nullable

Defines the app details (about, terms and conditions, privacy policy)

about
Object nullable

Details about us (URL or contact should be specified)

url
string required nullable

The about URL

Example:
https?/crm.com
content
string required nullable

The about rich content

Example:
About Us
terms_conditions
Object nullable

Details about the terms and conditions (URL or contact should be specified)

url
string required nullable

The terms and conditions URL

Example:
https?/crm.com
content
string required nullable

The terms and conditions rich content

Example:
Terms & Conditions
privacy_policy
Object nullable

Details about the privacy policy (URL or contact should be specified)

url
string required nullable

The privacy policy URL

Example:
https?/crm.com
content
string required nullable

The privacy policy rich content

Example:
Privacy Policy
faqs
Object nullable

Details about the FAQs (URL or contact should be specified)

url
string required nullable

The FAQs URL

Example:
https?/crm.com
content
string required nullable

The FAQs rich content

Example:
FAQs
contact_us
Object nullable

Details about contact us

email_address
string nullable

The contact us email address

Example:
info@crm.com
phone_country_code
string nullable

The contact us phone number country code

Example:
CYP
phone_number
string nullable

The contact us phone number

Example:
22265566
website
string nullable

The contact us website

Example:
https?/crm.com
features
Object nullable

Details about the features that will be supported by the app

billing
boolean required

Defines whether billing feature is supported

Example:
false
rewards
boolean required

Defines whether rewards feature is supported

Example:
true
ordering
boolean required

Defines whether ordering feature is supported

Example:
true
subscriptions
boolean

Defines whether subscriptions feature is supported

finance
boolean required

Defines whether finance feature is supported

Example:
false
crm
boolean required

Defines whether crm feature is supported

Example:
true
business_network
boolean required

Defines whether business network feature is supported

Default:
false
Example:
false
marketing_content
boolean required

Defines whether Marketing Content feature is supported

Default:
false
Example:
false
business_network_details
Object required nullable

Defines the supported business network items (only if business network feature is supported)

multitenancy
boolean required

Defines whether multitenancy will be supported

Example:
true
contact
Object

Supported contact features for app & portal

is_supported
boolean

Are contact features supported?

Example:
true
code_representation
string nullable

How the contact code will be depicted on the app/portal, for scanning purposes

Enumeration:
BARCODE

As a barcode

QR_CODE

As a QR code

Example:
BARCODE
crm_details
Object nullable

Defines the supported crm items

service_requests
boolean required

Defines whether contacts will be able to create service requests

Example:
false
finance_details
Object required nullable

Defines the supported finance items (only if finance feature is supported)

wallet_top_up
boolean required

Defines whether contacts will be able to top up their wallets

Example:
true
redeem_pass
boolean required

Defines whether contacts will be able to redeem a pass

Example:
true
redeem_pass_attributes
Array nullable

Defines whether redeem pass should be supported by other attributes

string

The type of supplementary attribute

Enumeration:
CODE
VALUE
PIN
ordering_details
Object required nullable

Defines the supported ordering items (only if ordering feature is supported)

ordering_pickup
boolean required

Defines whether pick up is supported as supply method

Example:
true
ordering_delivery
boolean required

Defines whether delivery is supported as supply method

Example:
true
ordering_direct_sale
boolean

Defines whether direct sale is supported as supply method

Example:
true
preferred_organisation_orders
boolean

Defines whether contact can set preferred organisation for ordering

Example:
true
ordering_countries
Array

Defines the countries where orders will be applicable

Object
country
string

The country (code)

Example:
CYP
allow_wallet_funds_payment
boolean required

Defines whether contact can pay for order using wallet funds

Default:
false
Example:
true
allow_specific_funds_amount
boolean nullable

Defines whether contacts can specific the wallet funds amount to use on orders

Default:
false
Example:
false
allow_full_basket_wallet_fund
boolean

Defines whether the wallet fund amount must cover the full basket amount

Example:
true
order_catalogs
Array nullable

Defines a list of order catalogs that should filter available products to order

Object
id
string GUID required

The order catalog identifier

Example:
676055d9-fe79-6836-8a50-c2d3764e9919
rewards_details
Object required nullable

Defines the supported rewards items (only if rewards feature is supported)

automatic_spends
boolean required

Defines whether automatic spend preferences will be supported

Example:
true
automatic_spend_options
Object

Details about the automatic spend settings that a contact can set up

any_purchase
boolean required

Defines whether automatic spends can be set for any purchase

Example:
true
any_purchase_collect_on
string required nullable

Defines whether contact can set preferred merchants on which automatic spends wil be applied (applicable and required only if any_purchase = true)

Enumeration:
ANY_MERCHANT

Contact auto spends will be applied on all merchant purchases

PREFERRED_MERCHANT

Contact will have the ability to select the merchants that auto spends will be applied

Default:
ANY_MERCHANT
next_purchase_merchant
boolean required

Defines whether automatic spends can be set for next purchase at merchant X

Example:
true
return_cashback
boolean required

Defines whether the ability to select payment method for cashback returns will be supported

Example:
false
customer_selfservice_purchases
boolean required

Defines whether customer self service purchase identification will be supported

Example:
true
reclaim_purchase_methods
Array required nullable

Defines how reclaim purchase identification will be made (required when contact self-submit purchase is enabled)

string
Enumeration:
BARCODE
TRX_CODE
reward_tiering
boolean required

Defines whether reward tiering will be supported

Example:
true
preferred_organisation_rewards
boolean

Defines whether contact can set preferred organisation for rewards

Example:
true
refer_friend
boolean required

Defines whether refer a friend will be supported

Default:
true
Example:
true
refer_friend_communication_method
string nullable

Defines the communication method that should be used for refer a friend

Enumeration:
EMAIL
SMS
Default:
EMAIL
otp_spend
boolean nullable

Defines whether OTP send will be supported

Default:
false
Example:
true
otp_spend_attributes
Array nullable

Defines the supplementary attributes that will be supported for OTP spends

string
Enumeration:
AMOUNT
marketing_content_details
Object

Defines marketing content to display in front-end systems

embedded_links
Array

Define links for embedded browser in front-end systems

Object
title
string

Defines the title of the link

Example:
New and upcoming events
url
string

Defines the URL of the link

Example:
https://www.guababechbar.com/news&events
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
merchant_app
Object

Defines the supported Merchant app items

allow_spend
boolean

Defines whether the merchant app supports submission of Spend requests

Default:
false
Example:
true
restrict_fully_covered
boolean

Defines whether the purchase (front-end reduction) will be posted successfully only if requested spend amount fully covers the purchase amount

Example:
true
contact
Object nullable

Details on supported contact attributes

profile_details
Array nullable

Lists all supported contact attributes

Unique items: YES
Object
type
string required

The contact attribute

Enumeration:
BIRTHDATE
NAMEDAY
GENDER
is_supported
boolean nullable

Defines if the profile attribute is supported or not

Default:
false
Example:
false
auth_support
Object nullable

Details on how customers can auth by the app

email_password
boolean required

Supported authentication based on email and password

Example:
true
email_otp
boolean required nullable

Supported authentication based on email and one time password

Example:
true
sms_otp
boolean required

Supported authentication based on one time password

Example:
true
activate_demo_contact
boolean required nullable

Enable to define a demo contact from existing contacts

Default:
false
Example:
true
demo_contact_details
Object required nullable

The contact assigned as demo contact

contact_id
string GUID required

The id of contact assigned as demo contact

Example:
BA84F57FC19A4ECB84EE779957364B83
otp
string required

The otp to accept for signing in

Example:
123456
facebook
boolean required

Supported authentication based on Facebok

Example:
true
fb_app_id
string required nullable

Facebook App ID required for FB authentication (applicable and required when Facebook authentication is enabled)

Example:
dsf-w-f-esf-23f-w-eff2f
fb_app_secret
string required nullable

Facebook App Secret for Server to Server communication (must not be sent to client) (applicable and required when Facebook authentication is enabled)

Example:
qqsdf-23-we-wer-3ew-qq
google
boolean required

Supported authentication based on Google

Example:
true
google_app_id
string required nullable

Google App ID required for Google authentication (applicable and required when Google authentication is enabled)

Example:
dsf-w-f-esf-23f-w-eff2f
google_app_secret
string required nullable

Google App Secret for Server to Server communication (must not be sent to client) (applicable and required when Google authentication is enabled)

Example:
qqsdf-23-we-wer-3ew-qq
manage_credentials
Object required

Defines whether contacts will be able to manage their authentication details

add_new
boolean required

Defiens whether contact will be able to add new authentication details

Example:
true
update_existing
boolean required

Defiens whether contact will be able to update existing authentication details

Example:
true
delete_existing
boolean required

Defiens whether contact will be able to delete existing authentication details

Example:
true
app_identifiers
Array nullable

Details about the application identifiers per supported platform

Unique items: YES
Object
platform
string required

The platform on which the application will be published

Enumeration:
APPLE
GOOGLE
WEB
platform_app_id
string required

The application id for each platform

Example:
1762e052-4805-73eb-36f2-e77d6dc883e8
cloud_name
string
version
string required

The application version

Example:
1.1

Responses

200 200

Successfull Completed

Body
Object
id
string GUID

The application identifier

Example:
90f91e6b-54a4-6b93-5200-79ba9a361cb0
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/applications/f8343fdf-a91f-1def-a265-35ac78b0a3ba/settings HTTP/1.1 

Content-Type: application/json

{
    "appearance": {
        "background_color": "#eb4034",
        "card_color": "#eb4034",
        "button_color": "#eb4034",
        "landing_page_colours": {
            "background": "#eb4034",
            "button": "#36e3d7",
            "text": "#e3cf36"
        },
        "screen_colours": {
            "button": "#36e3d7",
            "wallet": "#eb4034",
            "card": "#eb4034"
        },
        "advanced_colour_mapping": "let appearance = { main_color: '#ffffff', //landing_page.text_color, landing_page.button_text_color, main_page.card_text_color, main_page.icon_color, side_bar.text_color, side_bar.icon_color, tab_bar.background_color button_color: '#50e3c2',//landing_page.button_color, main_page.button_color, main_page.button_selected, side_bar.background_color, tab_bar.selected, card_color: '#F0F0F3', //main_page.button_unselected, main_page.card_bg_color, main_page.input_background_color background_color: '#d32166', //landing_page.background_color text_normal_color: '#212121', //main_page.text_label_color, main_page.input_label_color text_main_color: '#03041D', //main_page.button_unselected_text_color, main_page.text_color, main_page.text_title_color, main_page.card_icon_color, main_page.input_text_color border_color: 'rgba(3, 4, 29, 0.16)', //main_page.border_button_color, main_page.border_input_color, tab_bar.unselected, darkmode_color: '#212121', //background pages when dark_mode = true darkmode_text: '#ffffff', //main_page.text_color }",
        "dark_mode": "false",
        "text_font": "Gilroy",
        "homepage_layout": "LAYOUT1"
    },
    "about_details": {
        "about": {
            "url": "https?/crm.com",
            "content": "About Us"
        },
        "terms_conditions": {
            "url": "https?/crm.com",
            "content": "Terms & Conditions"
        },
        "privacy_policy": {
            "url": "https?/crm.com",
            "content": "Privacy Policy"
        },
        "faqs": {
            "url": "https?/crm.com",
            "content": "FAQs"
        },
        "contact_us": {
            "email_address": "info@crm.com",
            "phone_country_code": "CYP",
            "phone_number": "22265566",
            "website": "https?/crm.com"
        }
    },
    "features": {
        "billing": "false",
        "rewards": true,
        "ordering": true,
        "subscriptions": true,
        "finance": "false",
        "crm": "true",
        "business_network": "false",
        "marketing_content": "false",
        "business_network_details": {
            "multitenancy": "true"
        },
        "contact": {
            "is_supported": "true",
            "code_representation": "BARCODE"
        },
        "crm_details": {
            "service_requests": "false"
        },
        "finance_details": {
            "wallet_top_up": "true",
            "redeem_pass": "true",
            "redeem_pass_attributes": [
                "VALUE"
            ]
        },
        "ordering_details": {
            "ordering_pickup": true,
            "ordering_delivery": true,
            "ordering_direct_sale": true,
            "preferred_organisation_orders": "true",
            "ordering_countries": [
                {
                    "country": "CYP"
                }
            ],
            "allow_wallet_funds_payment": "true",
            "allow_specific_funds_amount": "false",
            "allow_full_basket_wallet_fund": "true",
            "order_catalogs": [
                {
                    "id": "676055d9-fe79-6836-8a50-c2d3764e9919"
                }
            ]
        },
        "rewards_details": {
            "automatic_spends": "true",
            "automatic_spend_options": {
                "any_purchase": "true",
                "any_purchase_collect_on": "ANY_MERCHANT",
                "next_purchase_merchant": "true"
            },
            "return_cashback": "false",
            "customer_selfservice_purchases": "true",
            "reclaim_purchase_methods": [
                "TRX_CODE"
            ],
            "reward_tiering": "true",
            "preferred_organisation_rewards": "true",
            "refer_friend": "true",
            "refer_friend_communication_method": "EMAIL",
            "otp_spend": "true",
            "otp_spend_attributes": [
                "AMOUNT"
            ]
        },
        "marketing_content_details": {
            "embedded_links": [
                {
                    "title": "New and upcoming events",
                    "url": "https://www.guababechbar.com/news&events",
                    "creatives": [
                        {
                            "id": "CA123456789AQWSXZAQWS1236547896541",
                            "usage_type": "APP_LOGO",
                            "width": 2159,
                            "height": 3075,
                            "format": "jpg",
                            "url": "https://assets.crm.com/image/logo.jpg",
                            "public_id": "crm-com/image",
                            "media": [
                                {
                                    "width": 200,
                                    "height": 300,
                                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "merchant_app": {
            "allow_spend": true,
            "restrict_fully_covered": "true"
        }
    },
    "contact": {
        "profile_details": [
            {
                "type": "GENDER",
                "is_supported": "false"
            }
        ]
    },
    "auth_support": {
        "email_password": true,
        "email_verification": "true",
        "email_otp": "true",
        "sms_otp": true,
        "activate_demo_contact": "true",
        "demo_contact_details": {
            "contact_id": "BA84F57FC19A4ECB84EE779957364B83",
            "otp": "123456"
        },
        "facebook": true,
        "fb_app_id": "dsf-w-f-esf-23f-w-eff2f",
        "fb_app_secret": "qqsdf-23-we-wer-3ew-qq",
        "google": true,
        "google_app_id": "dsf-w-f-esf-23f-w-eff2f",
        "google_app_secret": "qqsdf-23-we-wer-3ew-qq"
    },
    "app_identifiers": [
        {
            "platform": "WEB",
            "platform_app_id": "1762e052-4805-73eb-36f2-e77d6dc883e8",
            "cloud_name": "",
            "version": "1.1"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "90f91e6b-54a4-6b93-5200-79ba9a361cb0"
}
Applications Media Group
POST /applications/{id}/media_groups
Add Applications Media Groups
POST /applications/{id}/media_groups

Create a new media group for a specific application

Path variables

id
string GUID required

The application (identifer) whose media groups will be set

Example:
6A24D2B5E44F44B28451FE021FCAD51E

Notes

MEDIA UPLOAD

Uploading media for an application requires the execution of the following APIs

  1. Create new Media Group
  2. Create Application Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 200

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/applications/6A24D2B5E44F44B28451FE021FCAD51E/media_groups HTTP/1.1 

Content-Type: application/json

{
    "name": "Default",
    "description": "Seasonal offer media"
}

HTTP/1.1 200 OK
POST /copyright_notice
GET /copyright_notice
POST /copyright_notice

Update the copyright notice (at Cloud Operator level only)

Notes

Applicable to be configured only by a “Cloud Operator” and will be applied throughout the software

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
copyright_text
string nullable

The actual copyright text

Example:
CRM.COM Software 2005-2021

Responses

200 OK

Success

Body
Object
id
string GUID

The organisation identifier

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/copyright_notice HTTP/1.1 

Content-Type: application/json

{
    "copyright_text": "CRM.COM Software 2005-2021"
}
GET /copyright_notice

Returns the copyright notice for a Cloud Operator

Request parameters

external _id
string required

The organisation’s external identifier

Example:
QWERTY12345671234567324ETFTGBY78

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
api_key
string optional

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
Object
copyright_text
string

The copyright text

Example:
CRM.COM Software 2005-2021
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/copyright_notice?external _id=QWERTY12345671234567324ETFTGBY78 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "copyright_text": "CRM.COM Software 2005-2021"
}
Countries of Agreement
PUT /agreement_countries
GET /agreement_countries
Update Supported Countries of Agreement
PUT /agreement_countries

Update the supported countries that contacts can agree to register against to

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
countries
Array required

Information about the supported countries

Object
country
string required

The supported country of agreement code

Example:
CYP
is_default
boolean required

Defines if the country is the default or not

Example:
true
currencies
Array

List of supported currencies per Country of agreement. If nothing is specified, then contacts of this Country of agremeent can have accounts in any of the suported currencies of the business, having the business base currency applied on creating a default account. If at elats one i specified then a default must be set

Unique items: YES
Object
currency_code
string required

The supported currecy code

Example:
EUR
is_default
boolean

The base currency of the Country of agreement. Having a default (one and only one) or base currecy is mandatory.

Example:
true

Responses

200 OK

Success

Body
Object
id
string GUID

The organisation identifier

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/agreement_countries HTTP/1.1 

Content-Type: application/json

{
    "countries": [
        {
            "country": "CYP",
            "is_default": "true",
            "currencies": [
                {
                    "currency_code": "EUR",
                    "is_default": "true"
                }
            ]
        }
    ]
}
Get Supported Countries of Agreement
GET /agreement_countries

Returns a list of the supported countries of agreement

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
country
string

The country (code)

Example:
CYP
is_default
boolean

Defines whether the country is the default one or not

currencies
Array

List of supported currencies per Country of agreement. If nothing is specified, then contacts of this Country of agremeent can have accounts in any of the suported currencies of the business, having the business base currency applied on creating a default account. If at elats one i specified then a default must be set

Unique items: YES
Object
currency_code
string

The supported currency code

Example:
EUR
is_default
boolean

The base currency of the Country of agreement. Having a default (one and only one) or base currecy is mandatory.

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/agreement_countries HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "country": "CYP",
            "is_default": true,
            "currencies": [
                {
                    "currency_code": "EUR",
                    "is_default": "true"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Currencies
POST /currencies
PUT /currencies/{id}
DELETE /currencies/{id}
GET /currencies
GET /currencies/{id}/rates
Add Currency
POST /currencies

Add a new currency

Notes

Currencies can be configured per Service Owner/Business organisations

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
code
string required

The currency code

Example:
EUR
rate
number required nullable

The conversaion rate of the currency in regards to the base currency (not required for default currency)

Default:
1
Example:
1.234

Responses

200 200

Successful Request

Body
Object
id
string GUID

The currency identifier

Example:
4AD9C84FA60F9FE407140E20F707726W
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://devapi.crm.com/backoffice/v1/organisations/CAD1E31269B76D7A65ACCE45B2E68DFD/currencies HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "code": "EUR",
    "rate": 1.234
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726W"
}
Update Currency
PUT /currencies/{id}

Update an existing currency

Path variables

id
string required

The currency (identifer) that will be updated

Example:
edf4a34c-4932-4941-9957-aeb5b55873b6

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
rate
number required nullable

The conversaion rate of the currency in regards to the base currency

Example:
1.2345

Responses

200 200

Successful Request

Body
Object
id
string GUID

The currency identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/organisations/edf4a34c-4932-4941-9957-aeb5b55873bW/currencies/edf4a34c-4932-4941-9957-aeb5b55873b6 HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "rate": 1.2345
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A"
}
Remove Currency
DELETE /currencies/{id}

Remove an existing currency from the supported ones

Path variables

id
string GUID required

The currency (identifer) that will be removed from the supported ones

Example:
4AD9C84FA60F9FE407140E20F707726W

Notes

Base Currency cannot be removed

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://devapi.crm.com/backoffice/v1/organisations/4AD9C84FA60F9FE407140E20F707726A/currencies/4AD9C84FA60F9FE407140E20F707726W HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
Get Currencies
GET /currencies

Search for currencies (search is applied between the supported ones per organisation and not all ISO 4217 supported currencies)

Request parameters

code
string optional

The currency code

Example:
EUR
is_default
boolean optional

If not specified, then all supported currencies are returned

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC
country_code
string optional

Country code. If set, then the supported currencies of that country will be returned. If the country does not have any, then the business’s currencies are returned

Example:
CYP

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The currency identifer

Example:
4AD9C84FA60F9FE407140E20F707726A
code
string

The currency code

Example:
EUR
rate
number

The conversion rate of the currency in regards to the base currency

Example:
1.234
is_default
boolean

Marks the base currency of an organisation

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/currencies HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "code": "EUR",
            "is_default": true
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Currency Rates History
GET /currencies/{id}/rates

Retrieve a supported currency’s history of rates

Path variables

id
string GUID required

The currency (identifer) that will be retrieved

Example:
4AD9C84FA60F9FE407140E20F707726W

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
rates
Array

Information about the currencty conversion rate history

Object
id
string GUID

The conversion rate identifier

Example:
4AD9C84FA60F9FE407140E20F707726W
rate
number

The conversion rate with the base currency

Example:
1.234
from_date
string epoch

The date from which the rate is effective

Example:
1588171696
to_date
string epoch

The date up to which the rate is effective

Example:
1588171696
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/organisations/4AD9C84FA60F9FE407140E20F707726A/currencies/4AD9C84FA60F9FE407140E20F707726W HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F70772ER",
    "code": "EUR",
    "rates": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726W",
            "rate": 1.234,
            "from_date": "1588171696",
            "to_date": "1588171696"
        }
    ]
}
Custom Fields
POST /custom_fields
PUT /custom_fields/{id}
DELETE /custom_fields/{id}
GET /custom_fields
GET /custom_fields/{id}/
POST /custom_fields/priorities
Create Custom Field
POST /custom_fields

Creates a new custom field

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
key
string required

The custom field key (for integrations and API purposes)

Example:
back_office
label
string required

The custom field label (for display purposes)

Example:
Back Office
description
string nullable

The custom field description

Example:
The account's back office code
tooltip
string nullable

The custom field tooltip

Example:
lorem ipsum
type
string required

The custom field’s UI field type

Enumeration:
SINGLE_LINE
MULTIPLE_LINES
SELECTION
CHECKBOX
RADIO_BUTTONS
TIMESTAMP
DATE
NUMBER
AMOUNT
CONTENT
NUMBERING_SCHEME
content
string required nullable

The custom field module (applicable only if type = module)

Enumeration:
USERS
entity
string

The type of the event

Enumeration:
CONTACTS
ORDERS
ORGANISATIONS
DEVICES
SERVICE_REQUESTS
PAYMENTS
REFUNDS
TOP_UPS
LEADS
ACTIVITIES
PASSES
visible
boolean required

Defines whether the custom field will be avaialble in the user interface or not

Example:
true
options
Array nullable

Applicable options for custom fields (required for selections, checkboxes and radio buttons)

Object
key
string required

The option key (for integrations and API purposes)

Example:
option_1
text
string required

The option text (for display purposes)

Example:
my option 1
default
boolean nullable

Defines whethet the option will be the default one or not

Example:
true
order_number
integer required

Defines the order that will be used for displaying purposes

Example:
1
maximum_allowed_chars
integer
maximum_number
number
minimum_number
number
number_of_decimals
integer
prefix
string
suffix
string
digits_number
integer
Default:
5
check_digit
boolean

Defines whether check digit (based on Luhn algorithm) will be generated (applicable for numbering scheme custom fields)

Default:
false
Example:
true

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The custom field identifier

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/custom_fields HTTP/1.1 

Content-Type: application/json

{
    "key": "back_office",
    "label": "Back Office",
    "description": "The account's back office code",
    "tooltip": "lorem ipsum",
    "type": "TIMESTAMP",
    "content": "USERS",
    "entity": "CONTACTS",
    "visible": true,
    "options": [
        {
            "key": "option_1",
            "text": "my option 1",
            "default": true,
            "order_number": 1
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a"
}
Update Custom Field
PUT /custom_fields/{id}

Updates an existing custom field

Path variables

id
string GUID required

The custom field (identifer) that will be updated

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
label
string
Example:
Back Office
description
string
Example:
The account's back office code
tooltip
string
Example:
Accounts Back Office Code
visible
boolean
Example:
true
options
Array nullable

Applicable options for custom fields (required for selections, checkboxes and radio buttons)

Object
key
string required

The option key (for integrations and API purposes)

Example:
option_1
text
string required

The option text (for display purposes)

Example:
my option 1
default
boolean nullable

Defines whethet the option will be the default one or not

Example:
true
order_number
integer required

Defines the order that will be used for displaying purposes

Example:
1
check_digit
boolean

Defines whether check digit (based on Luhn algorithm) will be generated (applicable for numbering scheme custom fields)

Example:
true
digits_number
integer
prefix
string
suffix
string
number_of_decimals
integer
maximum_number
number
minimum_number
number
maximum_allowed_chars
integer

Responses

200 200
Body
Object
id
string GUID

The custom field identifier

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/custom_fields/f68fad29-4a1b-3a1e-5cfa-6540a5b1609a HTTP/1.1 

Content-Type: application/json

{
    "label": "Back Office",
    "description": "The account's back office code",
    "tooltip": "Accounts Back Office Code",
    "visible": true,
    "options": [
        {
            "key": "option_1",
            "text": "my option 1",
            "default": true,
            "order_number": 1
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a"
}
Delete Custom Field
DELETE /custom_fields/{id}

Deletes a custom field

Path variables

id
string GUID required

The custom field (identifer) that will be deleted

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/custom_fields/f68fad29-4a1b-3a1e-5cfa-6540a5b1609a HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Custom Fields
GET /custom_fields

Returns a list of custom fields configured in the system

Request parameters

entity
string required

The name of the entity whose custom fields will be retrieved. If not specified, then all custom field across all entities are returned

Enumeration:
CONTACTS
ORDERS
ORGANISATIONS
DEVICES
SERVICE_REQUESTS
PAYMENTS
REFUNDS
TOP_UPS
LEADS
ACTIVITIES
PASSES

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Object
key
string

The custom field (unique) key

Example:
back_office
label
string

The custom field label

Example:
Back Office
description
string

The custom field description

Example:
The account's back office code
tooltip
string

The custom field tool-tip

Example:
lorem ipsum
type
string

The custom field’s UI field type

Enumeration:
SINGLE_LINE
MULTIPLE_LINES
SELECTION
CHECKBOX
RADIO_BUTTONS
TIMESTAMP
DATE
NUMBER
AMOUNT
CONTENT
NUMBERING_SCHEME
content
string

The custom field module (applicable only if type = module)

Enumeration:
USERS
entity
string

The type of the event

Enumeration:
CONTACTS
ORDERS
ORGANISATIONS
DEVICES
SERVICE_REQUESTS
PAYMENTS
REFUNDS
TOP_UPS
LEADS
ACTIVITIES
PASSES
visible
boolean

Defines whether the custom field is visible on the UI or not

Example:
true
options
Array

Details about the custom field options

Object
key
string

The field option key

Example:
option_1
text
string

The field option text

Example:
my option 1
default
boolean

Defines whther the field option is the default one

Example:
true
order_number
integer

The field option order number

Example:
1
check_digit
boolean

Defines whether check digit (based on Luhn algorithm) will be generated (applicable for numbering scheme custom fields)

Example:
true
maximum_allowed_chars
integer
maximum_number
number
minimum_number
number
number_of_decimals
integer
digits_number
integer
prefix
string
suffix
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/custom_fields?entity=LEADS HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a",
            "key": "back_office",
            "label": "Back Office",
            "description": "The account's back office code",
            "tooltip": "",
            "visible": true,
            "field": "TIMESTAMP",
            "entity": "DEVICES"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Custom Field
GET /custom_fields/{id}/

Returns details for a specific custom field

Path variables

id
string GUID required

The custom field (identifier) that will be retrieved

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
key
string

The custom field (unique) key

Example:
back_office
label
string

The custom field label

Example:
Back Office
description
string

The custom field description

Example:
The account's back office code
tooltip
string

The custom field tool-tip

Example:
lorem ipsum
type
string

The custom field’s UI field type

Enumeration:
SINGLE_LINE
MULTIPLE_LINES
SELECTION
CHECKBOX
RADIO_BUTTONS
TIMESTAMP
DATE
NUMBER
AMOUNT
CONTENT
NUMBERING_SCHEME
content
string

The custom field module (applicable only if type = module)

Enumeration:
USERS
entity
string

The type of the event

Enumeration:
CONTACTS
ORDERS
ORGANISATIONS
DEVICES
SERVICE_REQUESTS
PAYMENTS
REFUNDS
TOP_UPS
LEADS
ACTIVITIES
PASSES
visible
boolean

Defines whether the custom field is visible on the UI or not

Example:
true
options
Array

Details about the custom field options

Object
key
string

The field option key

Example:
option_1
text
string

The field option text

Example:
my option 1
default
boolean

Defines whther the field option is the default one

Example:
true
order_number
integer

The field option order number

Example:
1
check_digit
boolean

Defines whether check digit (based on Luhn algorithm) will be generated (applicable for numbering scheme custom fields)

Example:
true
maximum_allowed_chars
integer
maximum_number
number
minimum_number
number
number_of_decimals
integer
digits_number
integer
prefix
string
suffix
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/custom_fields/f68fad29-4a1b-3a1e-5cfa-6540a5b1609a/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "key": "back_office",
    "label": "Back Office",
    "description": "The account's back office code",
    "tooltip": "lorem ipsum",
    "type": "AMOUNTS",
    "content": "USERS",
    "entity": "DEVICES",
    "visible": true,
    "options": [
        {
            "key": "option_1",
            "text": "my option 1",
            "default": true,
            "order_number": 1
        }
    ]
}
Order / Priority of Custom Field
POST /custom_fields/priorities

Changes the order/priority of a custom field

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
panel_id
string GUID nullable

The panel identifier to be ordered (can be null if default form location)

Example:
57fa030e-4fd7-9829-2045-615e70905c59
new_priority
integer nullable

The new priority order

Example:
1

Responses

200 OK
Body
Object
panel_id
string GUID

The panel identifier

Example:
57fa030e-4fd7-9829-2045-615e70905c59
priority
integer

The priority

Example:
1
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
curl -X POST "https://sandbox.crm.com/backoffice/v1/custom_fields/priorities"  \
 -H "Content-Type: application/json"  \
 -H "authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV"  \
 -d '{
    "panel_id": "57fa030e-4fd7-9829-2045-615e70905c59",
    "new_priority": 1
}' 

HTTP/1.1 200 OK  
 
Content-Type: application/json 

{
    "panel_id": "57fa030e-4fd7-9829-2045-615e70905c59",
    "priority": 1
}
Custom Forms
POST /custom_forms
PUT /custom_forms/{id}
DELETE /custom_forms/{id}
GET /custom_forms
GET /custom_forms/{id}
Create Custom Form
POST /custom_forms

Creates a new custom form

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The custom form name

Example:
Register Customers
description
string nullable

The custom form description

Example:
Custom form flow
url_endpoint
string required

The URL endpoint where the form is hosted

Example:
http://crm.com/integrations/register-contact
signature
string required

Authentication signature that will verify that the form requests are trusted

Example:
46145c04-d4a4-827f-2863-49b2823fcf64
component
Object

Details about the UI details that should be applied for this custom form

icon
string

The icon to be used

Example:
mdi mdi-plus
name
string

The name to be displayed

Default:
if not specified. defaults to the custom form name
Example:
Register Contact
type
string

Defines whether the custom form should be loaded as modal or embedded data page

Enumeration:
MODAL
EMBEDDED
location
string

Defines where the custom form should exist (e.g. navigation menu, within a page)

Enumeration:
CONTACTS_SUMMARY
CONTACTS_DATAPAGE
life_cycle_state
string

The custom form life cycle state

Enumeration:
ACTIVE
INACTIVE
Default:
INACTIVE

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The custom form identifier

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/custom_forms HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Register Customers",
    "description": "Custom form flow",
    "url_endpoint": "http://crm.com/integrations/register-contact",
    "signature": "46145c04-d4a4-827f-2863-49b2823fcf64",
    "component": {
        "icon": "mdi mdi-plus",
        "name": "Register Contact",
        "type": "EMBEDED",
        "location": ""
    },
    "life_cycle_state": "INACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a"
}
Update Custom Form
PUT /custom_forms/{id}

Updates an existing custom form

Path variables

id
string GUID required

The custom form (identifier) to be updated

Example:
f6913302-f341-6a8b-8b22-adc4e006e0a6

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The custom form name

Example:
Register Customers
description
string nullable

The custom form description

Example:
Custom form flow
url_endpoint
string nullable

The URL endpoint where the form is hosted

Example:
http://crm.com/integrations/register-contact
signature
string nullable

Authentication signature that will verify that the form requests are trusted

Example:
46145c04-d4a4-827f-2863-49b2823fcf64
component
Object nullable

Details about the UI details that should be applied for this custom form

icon
string

The icon to be used

Example:
mdi mdi-plus
name
string

The name to be displayed

Default:
if not specified. defaults to the custom form name
Example:
Register Contact
type
string

Defines whether the custom form should be loaded as modal or embedded data page

Enumeration:
MODAL
EMBEDDED
location
string

Defines where the custom form should exist (e.g. navigation menu, within a page)

Enumeration:
CONTACTS_SUMMARY
CONTACTS_DATAPAGE
life_cycle_state
string nullable

The custom form life cycle state

Enumeration:
ACTIVE
INACTIVE
Default:
INACTIVE

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The custom form identifier

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/custom_forms/f6913302-f341-6a8b-8b22-adc4e006e0a6 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Register Customers",
    "description": "Custom form flow",
    "url_endpoint": "http://crm.com/integrations/register-contact",
    "signature": "46145c04-d4a4-827f-2863-49b2823fcf64",
    "component": {
        "icon": "mdi mdi-plus",
        "name": "Register Contact",
        "type": "MODAL",
        "location": ""
    },
    "life_cycle_state": "INACTIVE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "f68fad29-4a1b-3a1e-5cfa-6540a5b1609a"
}
Delete Custom Form
DELETE /custom_forms/{id}

Deletes an existing custom form

Path variables

id
string GUID required

The custom form (identifier) to be deleted

Example:
f6913302-f341-6a8b-8b22-adc4e006e0a6

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/custom_forms/f6913302-f341-6a8b-8b22-adc4e006e0a6 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Custom Forms
GET /custom_forms

Returns a list of custom fields configured in the system

Request parameters

name
string optional

Filters based on custom form name

Example:
register
life_cycle_state
string optional

Filters based on custom form life cycle state

Enumeration:
ACTIVE
INACTIVE
location
string optional

Filter based on custom form’s location

Enumeration:
CONTACTS_SUMMARY
CONTACTS_DATAPAGE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

The custom form identifier

Example:
30176eac-2ce3-0ea9-9418-7bd65aff8c56
name
string

The custom form name

Example:
Register
description
string

The custom form description

Example:
Custom Registration Form
url_endpoint
string

The URL endpoint where such custom form is hosted

Example:
http://crm.com/integrations/register
life_cycle_state
string

The custom form life cycle state

Enumeration:
ACTIVE
INACTIVE
component
Object

Details about the UI details that should be applied for this custom form

icon
string

The icon to be used

Example:
mdi mdi-plus
name
string

The name to be displayed

Example:
Register Contact
type
string

Defines whether the custom form should be loaded as modal or embedded data page

Enumeration:
MODAL
EMBEDDED
location
string

Defines where the custom form should exist (e.g. navigation menu, within a page)

Enumeration:
CONTACTS_SUMMARY
CONTACTS_DATAPAGE
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/custom_forms HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "30176eac-2ce3-0ea9-9418-7bd65aff8c56",
            "name": "Register",
            "description": "Custom Registration Form",
            "url_endpoint": "http://crm.com/integrations/register",
            "life_cycle_state": "ACTIVE"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Custom Form
GET /custom_forms/{id}

Returns details for a specific custom form

Path variables

id
string GUID required

The custom form (identifier) to be retrieved

Example:
4af1ee3a-a0f6-8a87-3d24-08a7d56c9ab9

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The custom form identifier

Example:
30176eac-2ce3-0ea9-9418-7bd65aff8c56
name
string

The custom form name

Example:
Register
description
string

The custom form description

Example:
Custom Registration Form
url_endpoint
string

The URL endpoint where the custom form is hosted

Example:
http://crm.com/integrations/register
signature
string

Authentication signature that will verify that the form requests are trusted

Example:
46145c04-d4a4-827f-2863-49b2823fcf64
component
Object

Details about the UI details that should be applied for this custom form

icon
string

The icon to be used

Example:
mdi mdi-plus
name
string

The name to be displayed

Example:
Register Contact
type
string

Defines whether the custom form should be loaded as modal or embedded data page

Enumeration:
MODAL
EMBEDDED
location
string

Defines where the custom form should exist (e.g. navigation menu, within a page)

Enumeration:
CONTACTS_SUMMARY
CONTACTS_DATAPAGE
life_cycle_state
string
Example:
ACTIVE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/custom_forms/4af1ee3a-a0f6-8a87-3d24-08a7d56c9ab9 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "30176eac-2ce3-0ea9-9418-7bd65aff8c56",
    "name": "Register",
    "description": "Custom Registration Form",
    "url_endpoint": "http://crm.com/integrations/register",
    "signature": "46145c04-d4a4-827f-2863-49b2823fcf64",
    "component": {
        "icon": "mdi mdi-plus",
        "name": "Register Contact",
        "type": "MODAL",
        "location": ""
    },
    "life_cycle_state": "ACTIVE"
}
Filters (Content Views)
POST /filters
PUT /filters/{id}
DELETE /filters/{id}
GET /filters
GET /filters/{id}
POST /filters/{id}/conditions
GET /filters/{id}/conditions
Create Filter
POST /filters

Create a new filter for a specific module

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The filter name

Example:
Active Discount Offers
module
string

The module for which the filter will be applied

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS
accessibility
Object required

Defines which organisations can be access and use it

type
string required

Defines which organisations can access and use it

Enumeration:
PRIVATE

Available only for the user that created it

MY_ORGANISATION

Available for all users under the same organisation

Default:
PRIVATE
Examples

Responses

200 200
Body
Object
id
string GUID

The filter identifier

Example:
ADD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/filter HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Active Discount Offers",
    "module": "OFFERS",
    "accessibility": {
        "type": "PRIVATE"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ADD1E31269B76D7A65ACCE45B2E68DFD"
}
Update Filter
PUT /filters/{id}

Update an existing filter

Path variables

id
string GUID required

The filter (identifier) that will be updated

Example:
49bad38a-efab-86cb-e501-e2c141099e50

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The filter name

Example:
Active Reward Offers
accessibility
Object nullable

Defines which organisations can be access and use it

type
string required

Defines which organisations can access and use it

Enumeration:
PRIVATE

Available only for the user that created it

MY_ORGANISATION

Available for all users under the same organisation

Default:
PRIVATE

Responses

200 200
Body
Object
id
string GUID

The filter identifier

Example:
ADD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/filters/49bad38a-efab-86cb-e501-e2c141099e50 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Active Discount Offers"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "ADD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete Filter
DELETE /filters/{id}

Delete an existing filter

Path variables

id
string GUID required

The filter (identifier) that will be deleted

Example:
49bad38a-efab-86cb-e501-e2c141099e50

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/filters/49bad38a-efab-86cb-e501-e2c141099e50 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Filters
GET /filters

Retrieve all filters

Request parameters

module
string optional

Narrow down filter results based on module

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS
include_conditions
boolean optional

Defines whether filter conditions should be returned as well

Example:
false
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The filter identifier

Example:
49bad38a-efab-86cb-e501-e2c141099e50
name
string

The filter name

Example:
Active Discount Offers
owner
Object

Defines the user that “owns” such filter

id
string GUID

The user identifier

Example:
b18f9bdc-9e37-ba35-9f7c-697cb9ed9ceb
module
string

The module for which the filter will be applied

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS
accessibility
Object

Defines how the segment can be accessed from business network

type
string

Defines which organisations can access and use it

Enumeration:
PRIVATE

Available only for the user that created it

MY_ORGANISATION

Available for all users under the same organisation

properties
Array
Object
property
string required

The attribute which will be considered as a filter

Example:
purchase.amount
operator
string required

The comparison operator between the property and the related value

Enumeration:
IS
IS_NOT
ON
BEFORE
AFTER
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
IS_EMPTY
IS_NOT_EMPTY
STARTS_WITH
DOES_NOT_START_WITH
ENDS_WITH
DOES_NOT_END_WITH
LIKE
NOT_LIKE
EQUAL
NOT_EQUAL
LESS_THAN_OR_EQUAL
MORE_THAN_OR_EQUAL
Default:
IS
min_value
string required

The (primary) value that will be compared to the property

Example:
5.00
max_value
string

The (secondary) value that will be compared to the property, applicable for range comparisons

Example:
10
value_list
Array

The record (identifier) that will be compared to the propery (applicable when filtering based on specific records, such as specific contacts, offers, products)

Example:
[
    "1ccf5401-e4b1-d173-2301-4c639b62c26f"
]
string GUID
Example:
1ccf5401-e4b1-d173-2301-4c639b62c26f
type
string required

The type of the propery attribute

Enumeration:
STRING
NUMBER
INTEGER
DATE
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/filters HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "49bad38a-efab-86cb-e501-e2c141099e50",
            "name": "Active Discount Offers",
            "module": "OFFERS"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Filter
GET /filters/{id}

Retrieve all attributes of a specific filter

Path variables

id
string GUID required

The filter (identifier) which attributes will be retrieved

Example:
514aefa7-ec78-3229-e70e-9935c84fa0b9

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string GUID

The filter identifier

Example:
49bad38a-efab-86cb-e501-e2c141099e50
name
string

The filter name

Example:
Active Discount Offers
accessibility
Object

Defines how the segment can be accessed from business network

type
string

Defines which organisations can access and use it

Enumeration:
PRIVATE

Available only for the user that created it

MY_ORGANISATION

Available for all users under the same organisation

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/filters/514aefa7-ec78-3229-e70e-9935c84fa0b9 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "49bad38a-efab-86cb-e501-e2c141099e50",
    "name": "Active Discount Offers",
    "accessibility": {
        "type": "ACROSS_NETWORK"
    }
}
Add Filter Conditions
POST /filters/{id}/conditions

Add a set of conditions on a specific filter

Path variables

id
string GUID required

The filter (identifier) whose conditions will be set

Example:
49bad38a-efab-86cb-e501-e2c141099e50

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
properties
Array required
Object
property
string required

The attribute which will be considered as a filter

Example:
purchase.amount
operator
string required

The comparison operator between the property and the related value

Enumeration:
IS
IS_NOT
ON
BEFORE
AFTER
BETWEEN
MORE_THAN
LESS_THAN
CONTAINS
DOES_NOT_CONTAIN
IS_EMPTY
IS_NOT_EMPTY
STARTS_WITH
DOES_NOT_START_WITH
ENDS_WITH
DOES_NOT_END_WITH
LIKE
NOT_LIKE
EQUAL
NOT_EQUAL
LESS_THAN_OR_EQUAL
MORE_THAN_OR_EQUAL
Default:
IS
min_value
string required

The (primary) value that will be compared to the property

Example:
5.00
max_value
string

The (secondary) value that will be compared to the property, applicable for range comparisons

Example:
10
value_list
Array

The record (identifier) that will be compared to the propery (applicable when filtering based on specific records, such as specific contacts, offers, products)

Example:
[
    "1ccf5401-e4b1-d173-2301-4c639b62c26f"
]
string GUID
Example:
1ccf5401-e4b1-d173-2301-4c639b62c26f
type
string required

The type of the propery attribute

Enumeration:
STRING
NUMBER
INTEGER
DATE

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/filters/49bad38a-efab-86cb-e501-e2c141099e50/conditions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "properties": [
        {
            "property": "purchase.amount",
            "operator": "IS",
            "min_value": "5.00",
            "type": "NUMBER"
        }
    ]
}

HTTP/1.1 200 OK 
Get Filter Conditions
GET /filters/{id}/conditions

Return a filter’s set of conditions

Path variables

id
string GUID required

The filter (identifier) whose conditions will be retrieved

Example:
9cf9c00a-c391-d91c-7657-f94ffe331b3d

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
property
string

The attribute which will be considered as a filter

Example:
purchase.amount
operator
string

The comparison operator between the property and the related value

Example:
MORE_THAN
min_value
string

The (primary) value that will be compared to the property

Example:
5.00
max_value
string

The (secondary) value that will be compared to the property, applicable for range comparisons

Example:
10
value_list
Array

The record (identifier) that will be compared to the propery (applicable when filtering based on specific records, such as specific contacts, offers, products)

Example:
[
    "1ccf5401-e4b1-d173-2301-4c639b62c26f"
]
string GUID
Example:
1ccf5401-e4b1-d173-2301-4c639b62c26f
type
string

The type of the propery attribute

Enumeration:
STRING
NUMBER
INTEGER
DATE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/filters/9cf9c00a-c391-d91c-7657-f94ffe331b3d/conditions HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "property": "purchase.amount",
            "operator": "IS",
            "min_value": "5.00",
            "type": "NUMBER"
        }
    ]
}
User Filters
POST /users/{id}/filters
GET /users/{id}/filters
Save Filter (User)
POST /users/{id}/filters

Saves the latest filter applied on a summary page by the user for a specific module

Path variables

id
string GUID required

The user (identifier) for which the filter will be set

Example:
03397197-6e67-ab75-ae69-76d3d66e06fb

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
module
string required

The module for which the filter will be applied

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS
filter_id
string GUID required

The filter (identifier) that will be set as the default of the related module

Example:
9a3c41c6-3450-bb0a-10d2-acbfd836a385

Responses

200 OK
Body
Object
id
string GUID

The filter identifier

Example:
a4896470-09c4-bd61-7502-4c4bc54fb6d6
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/users/03397197-6e67-ab75-ae69-76d3d66e06fb/filters HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "module": "AUTOMATIONS",
    "filter_id": "9a3c41c6-3450-bb0a-10d2-acbfd836a385"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a4896470-09c4-bd61-7502-4c4bc54fb6d6"
}
Get Filter (User)
GET /users/{id}/filters

Retrieves the latest filters applied on a summary page by the user for specific modules

Path variables

id
string GUID required

The user (identifier) for which the filter will be reteived

Example:
03397197-6e67-ab75-ae69-76d3d66e06fb

Request parameters

module
string optional

Narrow down filter results based on module

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

Successful Request

Body
Object
module
string

The module for which the filter will be applied

Enumeration:
ACTIVITIES
API_KEYS
AUTOMATIONS
CE_CLASSIFICATIONS
SERVICE_REQUESTS
REWARD_OFFERS
REWARD_SCHEMES
TAPS
USERS
WEBHOOKS
ORDERS
PRODUCT_CATALOG
CONTACTS
PROMOTIONS
REWARD_EVENTS
filter
Object

The existing filter previously applied by the user

id
string GUID

The filter identier

Example:
26fb9432-75ca-628e-50ef-3c7be9466bc5
name
string

The name of the filter

Example:
My Filter
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/users/03397197-6e67-ab75-ae69-76d3d66e06fb/filters HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "module": "ACTIVITIES",
    "filter": {
        "id": "26fb9432-75ca-628e-50ef-3c7be9466bc5",
        "name": "My Filter"
    }
}
Industries and Industry Sectors
Industries
POST /industries
PUT /industries/{id}
DELETE /industry/{id}
GET /industries
GET /industries/{id}
Create Industries
POST /industries

Create a new industry

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the industry to be created

Example:
TRAVEL

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry identifier

Example:
289be4e0-4d54-6bec-3517-bd27bc67c1ac
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/industries HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "TRAVEL"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "289be4e0-4d54-6bec-3517-bd27bc67c1ac"
}
Update Industries
PUT /industries/{id}

Update a specific instustry

Path variables

id
string GUID required

The industry (identifier) that will be updated

Example:
c18fb5e3-3ecb-c5ed-016c-16fa584a5203

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the industry to be updated

Example:
Marketing

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry identifier

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/industries/c18fb5e3-3ecb-c5ed-016c-16fa584a5203 HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "Marketing"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Industry
DELETE /industry/{id}

Delete an industry

Path variables

id
string GUID required

The industry (identifier) that will be deleted

Example:
c18fb5e3-3ecb-c5ed-016c-16fa584a5203

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/industry/c18fb5e3-3ecb-c5ed-016c-16fa584a5203 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Industries
GET /industries

Retrieve the contact industries

Request parameters

name
string optional

The name of the industry

Example:
EDUCATION
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The industry identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The industry name

Example:
Travel
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/industries HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Travel"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Industry
GET /industries/{id}

Retrieve a single industry

Path variables

id
string GUID required

The industry (identifier) that will be retrieved

Example:
c18fb5e3-3ecb-c5ed-016c-16fa584a5203

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The industry name

Example:
Travel
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/industries/c18fb5e3-3ecb-c5ed-016c-16fa584a5203 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A",
    "name": "Travel"
}
Industry Sectors
POST /industry_sectors
PUT /industry_sectors/{id}
DELETE /industry_sectors/{id}
GET /industry_sectors
GET /industry_sectors/{id}
Create Industry Sectors
POST /industry_sectors

Create the industry sectors

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the industry sector to be updated

Example:
TRAVEL AGENTS
related_industries
Array required

The industries that are associated with the industry sector

Object
industry_id
string GUID required

The industry (identifieR) related to the industry sectors

Example:
4AD9C84FA60F9FE407140E20F707726A

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry sector identifier

Example:
d6e7e8ce-5516-4153-9e94-63f5ff54511b
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/industry_sectors HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "TRAVEL AGENTS",
    "related_industries": [
        {
            "industry_id": "4AD9C84FA60F9FE407140E20F707726A"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "d6e7e8ce-5516-4153-9e94-63f5ff54511b"
}
Update Industry Sectors
PUT /industry_sectors/{id}

Update a specific Industry Sector

Path variables

id
string GUID required

The industry sector (identifier) that will be updated

Example:
d6e7e8ce-5516-4153-9e94-63f5ff54511b

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The name of the industry sector to be updated

Example:
Science
related_industries
Array nullable

The industries that are associated with the industry sector

Object
industry_id
string GUID required

The industry (identifier)

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry sector identifier

Example:
d6e7e8ce-5516-4153-9e94-63f5ff54511b
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/industry_sectors/d6e7e8ce-5516-4153-9e94-63f5ff54511b HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "name": "",
    "related_industries": [
        {
            "industry_id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "d6e7e8ce-5516-4153-9e94-63f5ff54511b"
}
Delete Industry Sector
DELETE /industry_sectors/{id}

Delete an industry sector

Path variables

id
string GUID required

The industry sector (identifier) that will be deleted

Example:
d6e7e8ce-5516-4153-9e94-63f5ff54511b

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/industry_sectors/d6e7e8ce-5516-4153-9e94-63f5ff54511b HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 
List Industry Sectors
GET /industry_sectors

Retrieve the industry sectors

Request parameters

name
string optional

The name of the industry sector

Example:
RESTAURANTS
industry_name
string optional

The name of the industry that multiple sectors belong to

Example:
EDUCATION
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
order
string optional

Defines how the results will be ordered

Default:
DESC

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
content
Array
Object
id
string GUID

The industry sector identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The industry sector name

Example:
Science
related_industries
Array

The industries that are associated with the industry sector

Object
id
string GUID

The industry identifier

Example:
d6e7e8ce-5516-4153-9e94-63f5ff54511b
name
string

The industry name

Example:
Computer
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/industry_sectors HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Science",
            "related_industries": [
                {
                    "id": "d6e7e8ce-5516-4153-9e94-63f5ff54511b",
                    "name": "Computer"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Industry Sector
GET /industry_sectors/{id}

Get details for a single industry sector

Path variables

id
string GUID required

The industry sector (identifier) that will be retrieved

Example:
f47e682a-5910-4714-9030-44469e2a6f85

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
id
string GUID

The industry sector identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The industry sector name

Example:
Science
related_industries
Array

The industries that are associated with the industry sector

Object
id
string GUID

The industry identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The industry name

Example:
Computer
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/industry_sectors/f47e682a-5910-4714-9030-44469e2a6f85 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "4AD9C84FA60F9FE407140E20F707726A",
    "name": "Science",
    "related_industries": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Computer"
        }
    ]
}
Landing Pages

Set up of a web page which serves as the entry point for a website or a particular section of a website.

POST /landing_pages
PUT /landing_pages/{id}
DELETE /landing_pages/{id}/
GET /landing_pages
GET /landing_pages/{id}
POST /landing_pages/{id}/actions
POST /landing_pages/{id}/attributes
PUT /landing_pages/{id}/attributes/
GET /landing_pages/{id}/attributes/
POST /landing_pages/{id}/fields
PUT /landing_pages/{id}/fields
GET /landing_pages/{id}/fields
POST /landing_pages/{id}/media_groups
Create Landing page
POST /landing_pages

Creates a landing page for an organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
name
string required

The name of the landing page

Example:
Enrolment form for Mobile pass cards
description
string

The description of the landing page

Example:
Enrolment landing page for mobile pass cards.
type
string required

The type of landing page

Enumeration:
REGISTER
PURCHASE_PASS
mobile_pass
boolean

Allow provision of mobile pass after registeration.

pass_plan_id
string

Pass plan id - in cases where ‘type’ = PURCHASE_PASS (i.e. the landing page is used for purchasing a gift pass)

Example:
5f1316d2-dfce-42f0-b7bf-c543b8df7702

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page created

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
POST https://sandbox.crm.com/backoffice/v1/landing_pages HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "Enrolment form for Mobile pass cards",
    "description": "Enrolment landing page for mobile pass cards.",
    "type": "PURCHASE_PASS",
    "mobile_pass": true,
    "pass_plan_id": "5f1316d2-dfce-42f0-b7bf-c543b8df7702"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Update Landing Page
PUT /landing_pages/{id}

Updates a landing page for an organisation

Path variables

id
string required

The GUID of the landing page to be updated.

Example:
HGSFGKSFGH1323

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
name
string required

The name of the landing page

Example:
Enrolment form for Mobile pass cards
description
string

The description of the landing page

Example:
Enrolment landing page for mobile pass cards.
type
string required

The type of landing page

Enumeration:
REGISTER
PURCHASE_PASS
mobile_pass
boolean

Allow provision of mobile pass

pass_plan_id
string

Pass plan id - in cases where ‘type’ = PURCHASE_PASS (i.e. the landing page is used for purchasing a gift pass)

Example:
5f1316d2-dfce-42f0-b7bf-c543b8df7702

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page created

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
PUT https://sandbox.crm.com/backoffice/v1/landing_pages/HGSFGKSFGH1323 HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "Enrolment form for Mobile pass cards",
    "description": "Enrolment landing page for mobile pass cards.",
    "type": "PASSWORD RESET",
    "mobile_pass": true
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Delete Landing Page
DELETE /landing_pages/{id}/

Deletes fields for a landing page form.

Path variables

id
string required

The guid of the landing page.

Example:
HGAHJDGF765GHFAHGD6575

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Array
Object
id
string

The GUID of the landing page that was deleted

Example:
HGHFADGJF768HJGAFDJY6576
Example 1
DELETE https://sandbox.crm.com/backoffice/v1/landing_pages/HGAHJDGF765GHFAHGD6575/ HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

[
    {
        "id": "HGHFADGJF768HJGAFDJY6576"
    }
]
List Landing Pages
GET /landing_pages

Returns a list of Landing Pages

Request parameters

from_date
integer epoch optional

The date from which the landing page was created

Example:
1343423423
search_value
string optional

Search for landing pages based on their name or description

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
state
string optional

The state of the landing page

Example:
ACTIVE , INACTIVE

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The landing pages’s unique identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The landing pages’s name

Example:
Enrolment form for Mobile pass cards
description
string

The landing pages’s description

Example:
Enrolment landing page for mobile pass cards.
state
string

The state of the landing page

Enumeration:
ACTIVE
INACTIVE
link
string

the link associated to the landing page

Example:
https://abc.com
type
string

The landing page type

paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/landing_pages HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4AD9C84FA60F9FE407140E20F707726A",
            "name": "Enrolment form for Mobile pass cards",
            "description": "Enrolment landing page for mobile pass cards.",
            "state": "ACTIVE",
            "link": "https://abc.com"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Landing Page
GET /landing_pages/{id}

Retrieves a landing page for an organisation.

Path variables

id
string required

the GUID of the mobile pass card to be retrieved

Example:
JHGFDJYGDSYHFSHGFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Object
name
string

The name of the landing page.

Example:
My loyalty pass enrolment form
description
string

The description of the landing page

Example:
Enrolment landing page for mobile pass cards.
type
string

The type of landing page

Enumeration:
REGISTER
PURCHASE_PASS
link
string

The link associated to the landing page

Example:
https://abc.com
mobile_pass
boolean

Provision mobile pass after registration

pass_plan_id
string

Pass plan id - in cases where ‘type’ = PURCHASE_PASS (i.e. the landing page is used for purchasing a gift pass)

Example:
5f1316d2-dfce-42f0-b7bf-c543b8df7702
state
string

The state of the landing page.

Enumeration:
ACTIVE
INACTIVE
Example 1
GET https://sandbox.crm.com/backoffice/v1/landing_pages/JHGFDJYGDSYHFSHGFD HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "name": "My loyalty pass enrolment form",
    "description": "Enrolment landing page for mobile pass cards.",
    "type": "PASSWORD_RESET",
    "link": "https://abc.com",
    "mobile_pass": true,
    "state": "ACTIVE"
}
Perform Landing Page Action
POST /landing_pages/{id}/actions

Change the status of a landing page.

Path variables

id
string required

The GUID of the landing page whose status is to be changed.

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
status
string required

The new landing page status

Enumeration:
ACTIVE

The landing page link is live and ready for contacts to access.

INACTIVE

The landing page link is not live and ready for contacts to access.

Example:
ACTIVE
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the mobile pass card whose status was changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Activate mobile pass card

POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HPA1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "status": "ACTIVE"
}
Create landing Page form
POST /landing_pages/{id}/attributes

Creates a form for a landing page for an organisation.

Path variables

id
string required

the id of the landing page

Example:
HJAGFDUYFA6576

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
header
string

The text in the header

Example:
This is a header
title
string required

The title to be dispayed on the landing page

Example:
Enrolment form
description
string

The description on the landing page

Example:
Please enter detail to enrol for mobile pass cards.
footer
string

The footer text

Example:
Please sign up
button
string

The text to be displayed on the button

Example:
Submit
success
string

The success message to be displayed on the success response page.

Example:
Congratulations!
fail
string

The failure message to be displayed on the failure response page.

Example:
Failed.
logo_img_position
string

Positioning of the logo image

Enumeration:
LEFT
CENTER
RIGHT
colors
Array required

The functionality that this page is linked to

Object
type
string

The color

Enumeration:
BACKGROUND
HEADER
BUTTON
TEXT
FOOTER
HEADER_TEXT
FOOTER_TEXT
BUTTON_TEXT
value
string

the color code

Example:
FSR4ER
opacity
Array

The opacity of images displayed on the landing page

Object
image
string

The image type.

Enumeration:
HEADER
BACKGROUND
value
integer

The opacity percentage

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
POST https://sandbox.crm.com/backoffice/v1/landing_pages/HJAGFDUYFA6576/attributes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "header": "This is a header",
    "title": "Enrolment form",
    "description": "Please enter detail to enrol for mobile pass cards.",
    "footer": "Please sign up",
    "button": "Submit",
    "success": "Congratulations!",
    "fail": "Failed.",
    "logo_img_position": "CENTER",
    "colors": [
        {
            "type": "LABEL_TEXT",
            "value": "FSR4ER"
        }
    ],
    "opacity": [
        {
            "image": "BACKGROUND",
            "value": 1
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Update landing page form
PUT /landing_pages/{id}/attributes/

Updates a form for a landing page for an organisation.

Path variables

id
string required

the id of the landing page

Example:
HJAGFDUYFA6576

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
title
string required

The title to be dispayed on the landing page

Example:
Enrolment form
description
string

The description of the landing page

Example:
Enrolment landing page for mobile pass cards.
footer
string

The footer text

Example:
Please sign up
success
string

The message to be displayed upon success page.

Example:
Congratulations.
fail
string

The message to be displayed upon fail page.

Example:
Failed
logo_img_position
string

The position of the logo on the landing page

Enumeration:
LEFT
CENTER
RIGHT
header
string

The header text

Example:
Welcome!
button
string

The button text

Example:
Submit
colors
Array required

The functionality that this page is linked to

Object
type
string

The color on the landig page.

Enumeration:
BACKGROUND
HEADER
BUTTON
TEXT
FOOTER
HEADER_TEXT
BUTTON_TEXT
FOOTER_TEXT
value
string

the color code

Example:
FSR4ER
opacity
Array

The opacitiy of the images on the landing page

Object
image
string

The image type.

Enumeration:
HEADER
BACKGROUND
value
integer

The image opacity

Example:
1

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
PUT https://sandbox.crm.com/backoffice/v1/landing_pages/HJAGFDUYFA6576/attributes/{att_id} HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "title": "Enrolment form",
    "description": "Enrolment landing page for mobile pass cards.",
    "footer": "Please sign up",
    "success": "Congratulations.",
    "fail": "Failed",
    "logo_img_position": "RIGHT",
    "colors": [
        {
            "type": "TEXT",
            "value": "FSR4ER"
        }
    ],
    "opacity": [
        {
            "image": "BACKGROUND",
            "value": 1
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Get landing page form
GET /landing_pages/{id}/attributes/

Retrieves a landing pages form attributes for an organisation.

Path variables

id
string required

the GUID of the landing page to be retrieved

Example:
JHGFDJYGDSYHFSHGFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Object
title
string

The title to be dispayed on the landing page.

Example:
Enrolment form
description
string

The description on the landing page

Example:
Enrolment landing page for mobile pass cards.
footer
string

Footer text on form

Example:
Mobile Pass Card
success
string

The message to be displayed on the success page.

Example:
Congradulations
failed
string

The message to be displayed on the fail page.

Example:
Failed
logo_img_position
string

The position of the logo image

Enumeration:
LEFT
CENTER
RIGHT
header
string

The header text

Example:
Welcome!
button
string

The button text

Example:
Submit!
colors
Array

The distribution method applicable

Object
type
string
Enumeration:
BACKGROUND
HEADER
BUTTON
TEXT
FOOTER
HEADER_TEXT
FOOTER_TEXT
BUTTON_TEXT
value
string

the colour code returned

Example:
FDE56F
opacity
Array

The opacity of the images on the landing pages.

Object
image
string

The image type.

Enumeration:
HEADER
BACKGROUND
value
integer

The value of the opacity

Example:
1
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
Example 1
GET https://sandbox.crm.com/backoffice/v1/landing_pages/JHGFDJYGDSYHFSHGFD/attributes/ HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "title": "Enrolment form",
    "description": "Enrolment landing page for mobile pass cards.",
    "footer": "Mobile Pass Card",
    "success": "Congradulations",
    "failed": "Failed",
    "logo_img_position": "CENTER",
    "header": "Welcome!",
    "button": "Submit!",
    "colors": [
        {
            "type": "FOOTER_TEXT",
            "value": "FDE56F"
        }
    ],
    "opacity": [
        {
            "image": "BACKGROUND",
            "value": 1
        }
    ],
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "LANDING_PAGE_HEADER_IMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Create form fields
POST /landing_pages/{id}/fields

Creates a field for a form for a landing page for an organisation.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
form
Array

Details pertaining to the enrollment form fields

Object
property
string required

The property to be added as a field

Example:
contact.email
label
string

The label defined to the field

Example:
email
priority
string int required

The priority in which the fields are displayed on the row or the section

Example:
1 , 2 , 3

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
POST https://sandbox.crm.com/backoffice/v1/landing_pages/{id}/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "form": [
        {
            "property": "contact.email",
            "label": "email",
            "priority": "1 , 2 , 3"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Update form field
PUT /landing_pages/{id}/fields

Updates a field for a form for a landing page for an organisation.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
form
Array

Details pertaining to the enrollment form fields

Object
id
string GUID

The id of the field to be updated

Example:
JHGFSJG76576HJSFG
property
string

The property to be added as a field

Example:
contact.email
label
string

The label defined to the field

Example:
email
priority
string int

The priority in which the fields are displayed on the row or the section

Example:
1 , 2 , 3

Responses

201 Created
Body
Object
id
string GUID

The GUID of the landing page

Example:
HGJSDYGFUY87686GFJHFASD
Example 1
PUT https://sandbox.crm.com/backoffice/v1/landing_pages/{id}/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "form": [
        {
            "id": "JHGFSJG76576HJSFG",
            "property": "contact.email",
            "label": "email",
            "priority": "1 , 2 , 3"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HGJSDYGFUY87686GFJHFASD"
}
Get form fields
GET /landing_pages/{id}/fields

Retrieves a landing pages form fields for an organisation.

Path variables

id
string required

the GUID of the mobile pass card to be retrieved

Example:
JHGFDJYGDSYHFSHGFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Object
form
Array

Detials relatng to a field on the landing page form

Object
id
string

The guid of the field

Example:
JHAGDJGA6576HGGJ
property
string

The property to be added as a field

Example:
contact.email
label
string

The label defined to the field

Example:
email
priority
integer

The priority in which the fields are displayed on the row or the section

Example 1
GET https://sandbox.crm.com/backoffice/v1/landing_pages/JHGFDJYGDSYHFSHGFD/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "form": [
        {
            "id": "JHAGDJGA6576HGGJ",
            "property": "contact.email",
            "label": "email",
            "priority": 1
        }
    ]
}
Landing Pages Media Groups
POST /landing_pages/{id}/media_groups

Link a landing page with one or many Media Groups

Path variables

id
string GUID required

The landing page identifier that will be updated

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Notes

MEDIA UPLOAD

Uploading media for a landing page requires the execution of the following APIs

  1. Create new Media Group
  2. Create Landing Pages Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK
Languages
Update Supported Languages
PUT /languages

Update the supported languages that content can be translated to and communications can be sent to

Notes

Languages can be configured per Service Owner/Business organisations and are used for content translations (e.g. translating offer descriptions in other languages)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
languages
Array

Information about the supported currencies

Object
language
string

The supported glossary language code

Enumeration:
ENG

English

GRE

Greek

Responses

200 OK

Success

Body
Object
id
string GUID

The organisation identifier

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/organisations/7cc1b26a-459f-4b47-a09f-6b121ae947da/languages HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "languages": [
        {
            "language": "GRE"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7cc1b26a-459f-4b47-a09f-6b121ae947da"
}
Get Supported Languages
GET /languages

Returns a list of the supported languages that can be used in communications and content translations

Notes

Languages can be configured per Service Owner/Business organisations and are used for content translations (e.g. translating offer descriptions in other languages)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Object
id
string GUID

The language identifier

Example:
41f14cfa-029c-0e91-609a-289ca788b1a8
language
string

The language code

Example:
EN
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/languages HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "languages": {
        "id": "41f14cfa-029c-0e91-609a-289ca788b1a8",
        "language": "EN"
    }
}
Mobile Pass Cards

Mobile Pass Cards are the collective term for the non payment cards, such as coupons, loyalty cards, subscription cards, rewards and anything that is not a payment card. These mobile pass cards will be set up by the CRM.com user and shall be linked to contacts that ‘enroll’ into this card scheme.

POST /mobile_pass_cards
PUT /mobile_pass_cards/{id}
GET /mobile_pass_cards/
POST /mobile_pass_cards/{id}/actions
POST /mobile_pass_cards/{id}/fields
PUT /mobile_pass_cards/{id}/fields
GET /mobile_pass_cards/{id}/fields
POST /mobile_pass_cards/{id}/attributes
PUT /mobile_pass_cards/{id}/attributes
GET /mobile_pass_cards/{id}/attributes
POST /mobile_pass_cards/{id}/barcodes
PUT /mobile_pass_cards/{id}/barcodes
GET /mobile_pass_cards/{id}/barcodes
POST /mobile_pass_cards/{id}/media_groups
Create Mobile Pass Cards
POST /mobile_pass_cards

Creates a mobile pass card for an organisation.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
name
string

The name of the pass card

Example:
My loyalty pass
description
string

The description of the pass card

Example:
This card is for reward purposes.
default_wallet
string

The default android wallet

Enumeration:
GOOGLE PAY
OTHER
alt_wallet_provider
string

The alternative wallet provider if Other is selected as default android wallet

Enumeration:
WALLET_PASSES
PASSWALLET

Responses

201 Created
Body
Object
id
string GUID

The id of the mobile pass card that was created.

Example:
HFH6576JHVHGF8976
Example 1
POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "My loyalty pass",
    "description": "This card is for reward purposes.",
    "default_wallet": "OTHER",
    "alt_wallet_provider": "WALLET_PASSES"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HFH6576JHVHGF8976"
}
Update Mobile Pass Card
PUT /mobile_pass_cards/{id}

Updates a mobile pass card for an organisation.

Path variables

id
string required

The id of the mobile pass card

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
name
string

The name of the pass card

Example:
My loyalty pass
program_name
string

The name of the program that applies to this pass card

Example:
My loyalty program
description
string

The description of the pass card

Example:
This card is for reward purposes.
default_wallet
string

The default android wallet

Enumeration:
GOOGLE PAY
OTHER
alt_wallet_provider
string

The alternative wallet provider if other is selcted as default android wallet.

Enumeration:
WALLET_PASSES
PASSWALLET

Responses

200 OK
Body
Object
id
string GUID

The id of the mobile pass card

Example:
KHGJ675HGFHGF
Example 1
PUT https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/{id} HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "name": "My loyalty pass",
    "program_name": "My loyalty program",
    "description": "This card is for reward purposes.",
    "default_wallet": "OTHER",
    "alt_wallet_provider": "WALLET_PASSES"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "KHGJ675HGFHGF"
}
Get Mobile Pass Card
GET /mobile_pass_cards/

Retrieves a mobile pass card for an organisation.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Object
external_id
string

The external id of the mobile pass card

Example:
KJHSJHGF76765NVSFJBF
name
string

The name of the mobile pass card.

Example:
My loyalty pass
description
string

The descri-ption of the mobile pass card.

Example:
This card is for reward purposes.
default_wallet
string

The default android wallet to be used.

Enumeration:
GOOGLE_PAY

default

OTHER
alt_wallet_provider
string

If OTHER is selected this is the alternative wallet to be used to add passes to.

Enumeration:
PASSWALLET
WALLET_PASSES
status
string

The state of the mobile pass card

Enumeration:
ACTIVE
INACTIVE
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
Example 1
GET https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/ HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "external_id": "KJHSJHGF76765NVSFJBF",
    "name": "My loyalty pass",
    "description": "This card is for reward purposes.",
    "default_wallet": "OTHER",
    "alt_wallet_provider": "PASSWALLET",
    "status": "ACTIVE",
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "GOOGLE_STRIP_IMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Perform Mobile Pass Card Action
POST /mobile_pass_cards/{id}/actions

Change the status of a mobile pass card.

Path variables

id
string required

The GUID of the mobile pass card whose status is to be changed.

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
status
string required

The new mobile pass card status

Enumeration:
ACTIVE

The mobile pass card can be distributed to contacts

INACTIVE

The mobile pass card can not be distributed to contacts

Example:
ACTIVE
Examples

Responses

200 OK
Body
Object
id
string

The GUID of the mobile pass card whose status was changed

Example:
HPA1E31269B76D7A65ACCE45B2E68DFD
200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1

Activate mobile pass card

POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HPA1E31269B76D7A65ACCE45B2E68DFD/actions HTTP/1.1 

Content-Type: application/json

{
    "status": "ACTIVE"
}
Create mobile pass fields
POST /mobile_pass_cards/{id}/fields

Creates fields for a mobile pass card for an organisation.

Path variables

id
string required

The guid of the mobile pass card

Example:
HGAHJDGF765GHFAHGD6575

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
Fields
Array

Details regarding the fields added to the pass.

Object
platform
string required

The wallet platform to which this field relates to.

Enumeration:
APPLE
GOOGLE
location
string required

Whether the field is at a row or a section

Enumeration:
ROW
SECTION
WEB_LINK
location_number
string int required

The row or section number

Example:
1 , 2 , 3
side
string required

Whether the field is on the front or the back

Enumeration:
FRONT
BACK
priority
string int required

The priority in which the fields are displayed on the row or the section

Example:
1 , 2 , 3
label
string

The label defined to the field

Example:
Points
property
string

The property in that field

Example:
wallet.points , https://abc.com
property_value
string

The value of the property. Applicable only for platform APPLE and property portal_url

Example:
https//releaseportal.crm.com
type
string

The nature of the field

Enumeration:
WEB
CALENDAR
LOCATION
PHONE
EMAIL
PORTAL_URL
text_alignment
string

The placement of the text.

Enumeration:
LEFT
CENTER
RIGHT

Responses

201 Created
Body
Array
Object
id
string

The GUID of the field that was created

Example:
HGHFADGJF768HJGAFDJY6576
Example 1
POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HGAHJDGF765GHFAHGD6575/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "Fields": [
        {
            "platform": "GOOGLE",
            "location": "WEB_LINK",
            "location_number": "1 , 2 , 3",
            "side": "BACK",
            "priority": "1 , 2 , 3",
            "label": "Points",
            "property": "wallet.points , https://abc.com",
            "type": "EMAIL",
            "text_alignment": "RIGHT"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

[
    {
        "id": "HGHFADGJF768HJGAFDJY6576"
    }
]
Update mobile pass field
PUT /mobile_pass_cards/{id}/fields

Updates fields for a mobile pass card for an organisation.

Path variables

id
string required

The guid of the mobile pass card

Example:
HGAHJDGF765GHFAHGD6575

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Array
Object
id
string GUID

The id of the field to be updated.

Example:
JHGSJGDS7675HDGSJDHG
platform
string

The platform that relates to the field.

Enumeration:
GOOGLE
APPLE
location
string

The location where the field is located.

Enumeration:
SECTION
ROW
WEB_LINKS
location_number
string

The number of row or section where the field is located

Example:
1
side
string

The side of the pass card where the field is situated

Enumeration:
FRONT
BACK
priority
string

The order of the field in its section or row or side.

Example:
1
label
string

The label displayed on card.

Example:
Points
property
string

The crm.com property relating to that field

Example:
wallet.points , https://abc.com
property_value
string

The value of the property. Applicable only for platform APPLE and property portal_url

Example:
https://releaseportal.crm.com
type
string

The nature of the field

Enumeration:
WEB
CALENDAR
LOCATION
PHONE
EMAIL
PORTAL_URL
text_alignment
string

The alignment position of the field.

Enumeration:
LEFT
CENTER
RIGHT

Responses

201 Created
Body
Array
Object
id
string

The GUID of the pass that was created

Example:
HGHFADGJF768HJGAFDJY6576
Example 1
PUT https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HGAHJDGF765GHFAHGD6575/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

[
    {
        "id": "JHGSJGDS7675HDGSJDHG",
        "platform": "APPLE",
        "location": "ROW",
        "location_number": "1",
        "side": "FRONT",
        "priority": "1",
        "label": "Points",
        "property": "wallet.points , https://abc.com",
        "type": "WEB",
        "text_alignment": "LEFT"
    }
]

HTTP/1.1 201 Created 

Content-Type: application/json

[
    {
        "id": "HGHFADGJF768HJGAFDJY6576"
    }
]
Get mobile pass fields
GET /mobile_pass_cards/{id}/fields

Retrieves details for fields for a mobile pass card for an organisation.

Path variables

id
string required

The guid of the mobile pass card fields to be returned.

Example:
HGAHJDGF765GHFAHGD6575

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object

Responses

201 Created
Body
Array
Object
id
string

The GUID of the field

Example:
JHGAJHAGFJH7856JHGASDJ
platform
string required

The platform to which the field relates.

Enumeration:
GOOGLE
APPLE
location
string

The location on the mobile pass card to which the field relates to. If the field is on the back of the card then this value is null. See example.

Enumeration:
SECTION
ROW
WEB_LINK
location_number
string int

The row or section number relating to the location. If the field is on the back of the card then this value is null. See example.

Example:
1
side
string

The side on which the field is placed.

Enumeration:
FRONT
BACK
priority
string int

The order that this field is displayed as in its row, section or on the back.

Example:
1
label
string

The label of this field.

Example:
Points
property
string

The property that will be related to this field

Example:
wallet.points
property_value
string

The value of the property. Applicable only for platform APPLE and property portal_url

Example:
https://releaseportal.crm.com
type
string

The type relating to the nature of the field.

Enumeration:
WEB
LOCATION
EMAIL
CALENDAR
PHONE
PORTAL_URL
text_alignment
string

The alignment position on the pass.

Enumeration:
LEFT
CENTER
RIGHT
Example 1
GET https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HGAHJDGF765GHFAHGD6575/fields HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{}

HTTP/1.1 201 Created 

Content-Type: application/json

fields:[
    {
        "id": "JHGAJHAGFJH7856JHGASDJ",
        "platform": "APPLE",
        "location": "SECTION",
        "location_number": "1",
        "side": "BACK",
        "priority": "1",
        "label": "Points",
        "property": "wallet.points",
        "type": "WEB",
        "text_alignment": "RIGHT"
    }
]
Create mobile pass attributes
POST /mobile_pass_cards/{id}/attributes

Creates attribute values for mobile pass card for an organisation.

Path variables

id
string required

The id of the mobile pass card

Example:
JHGJSHGKHADVJHASFV

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
attributes
Array

The colours relating to the pass

Object
param_type
string

The type of parameter.

Enumeration:
COLOUR
FONT
attribute_type
string required

The type of attribute.

Enumeration:
BACKGROUND

the background colour.

TEXT

the text colour.

LABEL

the label colour.

value
string required

The value of the attribute

Example:
FA76VC1

Responses

201 Created
Body
Array
Object
id
string GUID

The id of the new attribute value created

Example:
HJGDJHGJSYDGF786876
Example 1
POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/JHGJSHGKHADVJHASFV/attributes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "attributes": [
        {
            "param_type": "COLOUR",
            "attribute_type": "LABEL",
            "value": "FA76VC1"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

[
    {
        "id": "HJGDJHGJSYDGF786876"
    }
]
Update mobile pass attributes
PUT /mobile_pass_cards/{id}/attributes

Creates attribute values for mobile pass card for an organisation.

Path variables

id
string required

The id of the mobile pass card

Example:
JHGJSHGKHADVJHASFV

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
attributes
Array

The colours relating to the pass

Object
id
string GUID

The id of the attribute to be updated

Example:
KHGDSHG768687JYFGJDS
param_type
string

The type of parameter.

Enumeration:
COLOR
FONT
attribute_type
string required

The type of color attribute

Enumeration:
BACKGROUND
TEXT
LABEL
value
string required

The value of the attribute

Example:
FA76VC1

Responses

201 Created
Body
Array
Object
id
string GUID

The id of the attribute updated

Example:
HJGDJHGJSYDGF786876
Example 1
PUT https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/JHGJSHGKHADVJHASFV/attributes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "attributes": [
        {
            "id": "KHGDSHG768687JYFGJDS",
            "param_type": "COLOUR",
            "attribute_type": "BACKGROUND",
            "value": "FA76VC1"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

[
    {
        "id": "HJGDJHGJSYDGF786876"
    }
]
Get mobile pass attributes
GET /mobile_pass_cards/{id}/attributes

Creates fields for a mobile pass card for an organisation.

Path variables

id
string required

The guid of the mobile pass card fields to be returned.

Example:
HGAHJDGF765GHFAHGD6575

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object

Responses

201 Created
Body
Array
Object
id
string GUID

The GUID of the attribute

Example:
KJFHGJHSDG6756HGFSJHG
param_type
string

The type of parameter.

Enumeration:
COLOUR
FONT
attribute_type
string

The attribute type which the value relates to.

Enumeration:
BACKGROUND
LABEL
TEXT
value
string

The value relating to the attribute. eg. Color code of the attributes.

Example:
FA76VC1
Example 1
GET https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/HGAHJDGF765GHFAHGD6575/attributes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{}

HTTP/1.1 201 Created 

Content-Type: application/json

attributes:[
    {
        "id": "KJFHGJHSDG6756HGFSJHG",
        "param_type": "FONT",
        "attribute_type": "BACKGROUND",
        "value": "FA76VC1"
    }
]
Create pass barcode
POST /mobile_pass_cards/{id}/barcodes

Creates a barcode for a mobile pass card for an organisation.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
type
string required

The type of barcode to be displayed on the pass

Enumeration:
PDF_417
QR_CODE
NONE
AZTEC
CODE_128
content
string lexicon

The content to be stored as the barcode. Defaulted to contacts.id as lexicon.

Enumeration:
contact.id
contact.loyalty_number
contact.code
format
string

The format of the barcode

Example:
PKBarcodeFormatPDF417
message_encoding
string

The message encoded into the barcode.

Example:
iso-8859-1

Responses

201 Created
Body
Object
id
string GUID

The id of the mobile pass card.

Example:
HFH6576JHVHGF8976
Example 1
POST https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/{id}/barcodes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "type": "QR_CODE",
    "content": "contacts.id",
    "format": "PKBarcodeFormatPDF417",
    "message_encoding": "iso-8859-1"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HFH6576JHVHGF8976"
}
Update pass barcode
PUT /mobile_pass_cards/{id}/barcodes

Updates a barcode for a mobile pass card for an organisation.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
type
string required

The type of barcode to be displayed on the pass

Enumeration:
PDF_417
QR_CODE
NONE
AZTEC
CODE_128
content
string lexicon

The content to be stored as the barcode. Defaulted to contacts.id as lexicon.

Enumeration:
contact.id
contact.loyalty_number
contact.code
format
string

The format of the barcode

Example:
PKBarcodeFormatPDF417
message_encoding
string

The message encoded into the barcode.

Example:
iso-8859-1

Responses

201 Created
Body
Object
id
string GUID

The id of the mobile pass card.

Example:
HFH6576JHVHGF8976
Example 1
PUT https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/{id}/barcodes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "type": "AZTEC",
    "content": "contacts.id",
    "format": "PKBarcodeFormatPDF417",
    "message_encoding": "iso-8859-1"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "HFH6576JHVHGF8976"
}
Get pass barcode
GET /mobile_pass_cards/{id}/barcodes

Retrieves a mobile pass card barcodes for an organisation.

Path variables

id
string required

the GUID of the mobile pass card to be retrieved

Example:
JHGFDJYGDSYHFSHGFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Responses

201 Created
Body
Object
type
string

The type of barcode to be added to the mobile wallet pass.

Enumeration:
PDF_417
QR_CODE
NONE
AZTEC
CODE_128
content
string lexicon

The content that will be passed in the barcode.

Enumeration:
contact.id
contact.loyalty_number
contact.code
format
string

The format of the barcode

Example:
PKBarcodeFormatPDF417
message_encoding
string

The message encoded into the barcode.

Example:
iso-8859-1
Example 1
GET https://sandbox.crm.com/backoffice/v1/mobile_pass_cards/JHGFDJYGDSYHFSHGFD/barcodes HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "type": "NONE",
    "content": "contact.code",
    "format": "PKBarcodeFormatPDF417",
    "message_encoding": "iso-8859-1"
}
Mobile Pass Cards Media Groups
POST /mobile_pass_cards/{id}/media_groups

Link a mobile pass card with one or many Media Groups

Path variables

id
string GUID required

The mobile pass card identifier that will be updated

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Notes

MEDIA UPLOAD

Uploading media for a mobile pass card requires the execution of the following APIs

  1. Create new Media Group
  2. Create Mobile Passes Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/products/3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb/media_groups HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]

HTTP/1.1 200 OK 
Partners

Service Owner partners

POST /partners
PUT /partners/{id}
DELETE /partners/{id}
GET /partners
GET /partners/{id}
POST /partners/{id}/media_groups
Create Partner
POST /partners

Creates a new Service Owner partner

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

Partner name

Example:
Yellow Umbrella Corp.
contact_person
Object

Contact person information

name
string

Contact person name

Example:
John Smith
email
string

Contact person email

Example:
john.smith@yellowumberlla.com
phone
string

Contact person phone number

Example:
22499019
country_code
string

Phone number country code

Example:
CYP
life_cycle_state
string

Partner life cycle state

Enumeration:
ACTIVE
INACTIVE
Example:
ACTIVE

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The unique partner identifier

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/partner HTTP/1.1 

Content-Type: application/json

{
    "name": "Yellow Umbrella Corp.",
    "contact_person": {
        "name": "John Smith",
        "email": "john.smith@yellowumberlla.com",
        "phone": "22499019",
        "country_code": "CYP"
    },
    "life_cycle_state": "ACTIVE"
}
Update Partner
PUT /partners/{id}

Update an existing Service Owner partner

Path variables

id
string GUID required

Unique partner id to be updated

Example:
f6913302-f341-6a8b-8b22-adc4e006e0a6

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

Partner name

Example:
Yellow Umbrella Corp.
contact_person
Object

Contact person information

name
string

Contact person name

Example:
John Smith
email
string

Contact person email

Example:
john.smith@yellowumberlla.com
phone
string

Contact person phone number

Example:
22499346
country_code
string

Phone number country code

Example:
CYP
life_cycle_state
string

Partner life cycle state

Enumeration:
ACTIVE
INACTIVE
Example:
ACTIVE

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The unique partner identifier updated

Example:
f68fad29-4a1b-3a1e-5cfa-6540a5b1609a
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/partner/f6913302-f341-6a8b-8b22-adc4e006e0a6 HTTP/1.1 

Content-Type: application/json

{
    "name": "Yellow Umbrella Corp.",
    "contact_person": {
        "name": "John Smith",
        "email": "john.smith@yellowumberlla.com",
        "phone": "22499346",
        "country_code": "CYP"
    },
    "life_cycle_state": "ACTIVE"
}
Delete Partner
DELETE /partners/{id}

Deletes an existing partner

Path variables

id
string GUID required

The unique partner identifier to be deleted

Example:
f6913302-f341-6a8b-8b22-adc4e006e0a6

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

List Partners
GET /partners

Returns a list of partners configured in the system

Request parameters

name
string optional

Filter based on partner name

Example:
Umbrella
life_cycle_state
string optional

Filter based on life cycle state

Enumeration:
ACTIVE
INACTIVE
Example:
ACTIVE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
content
Array
Object
id
string GUID

Unique partner identifier

Example:
30176eac-2ce3-0ea9-9418-7bd65aff8c56
name
string

Partner name

Example:
Yellow Umbrella Corp.
contact_person
string

Contact person name

Example:
John Smith
life_cycle_state
string

Partner life cycle state

Enumeration:
ACTIVE
INACTIVE
Example:
ACTIVE
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/partners HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "30176eac-2ce3-0ea9-9418-7bd65aff8c56",
            "name": "Yellow Umbrella Corp.",
            "contact_person": "John Smith",
            "life_cycle_state": "ACTIVE"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Partner
GET /partners/{id}

Returns details for a specific partner

Path variables

id
string GUID required

The unique partner id to be retrieved

Example:
4af1ee3a-a0f6-8a87-3d24-08a7d56c9ab9

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

The request has succeeded

Body
Object
id
string GUID

The unique partner identifier

Example:
30176eac-2ce3-0ea9-9418-7bd65aff8c56
name
string

The partner name

Example:
Yellow Umbrella Corp.
contact_person
Object

Contact person details

name
string

Contact person name

Example:
John Smith
email
string

Contact person email

Example:
john.smith@yellowumbrella.com
phone
string

Contact person phone

Example:
22480900
country_code
string

Phone country code

Example:
CYP
life_cycle_state
string

Partner life cycle state

Enumeration:
ACTIVE
INACTIVE
Example:
ACTIVE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/custom_forms/4af1ee3a-a0f6-8a87-3d24-08a7d56c9ab9 HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "30176eac-2ce3-0ea9-9418-7bd65aff8c56",
    "name": "Register",
    "description": "Custom Registration Form",
    "url_endpoint": "http://crm.com/integrations/register",
    "signature": "46145c04-d4a4-827f-2863-49b2823fcf64",
    "component": {
        "icon": "mdi mdi-plus",
        "name": "Register Contact",
        "type": "MODAL",
        "location": ""
    },
    "life_cycle_state": "ACTIVE"
}
Partners Media Groups
POST /partners/{id}/media_groups

Link an partner with one or more media groups

Path variables

id
string GUID required

The unique identifier of the partner to be updated

Example:
sdfsfsdf-32-fwef-wef-wefwef23

Notes

MEDIA UPLOAD

Uploading media for an partner requires the execution of the following APIs

  1. Create new Media Group
  2. Create Partner Media Groups
  3. Upload Media
  4. Perform Cloudinary Upload (where CRM will send all signature details)
  5. Cloudinary service calls back CRM media group (using an internal callback)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Array
Object
media_group_id
string GUID required

The media group identifier

Example:
3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/partners/sdfsfsdf-32-fwef-wef-wefwef23/media_groups HTTP/1.1 

Content-Type: application/json

[
    {
        "media_group_id": "3f1f9e63-7f40-4e5e-bc42-11a162f7f1fb"
    }
]
Service Owner Details

Allows to provide details about the service owner branding for the entire back-office experience

PUT /service_owner
GET /service_owner
Update Service Owner Details
PUT /service_owner

Update the service owner details

Notes

Applicable to be configured only by “Service Owner” organisations and will be applied across their business network (e.g. Businesses, Subsidiaries, Merchants)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
terms_service
string nullable

The terms of service URL

Default:
https://www.crm.com/terms-and-conditions/
Example:
https://www.crm.com/terms-and-conditions/
privacy_policy
string nullable

The privacy policy URL

Default:
https://www.crm.com/privacy-policy/
Example:
https://www.crm.com/privacy-policy/
pricing_policy
string nullable

The pricing policy URL

Example:
http://crm.com

Responses

200 OK

Success

Body
Object
id
string GUID

The organisation identifier

Example:
7cc1b26a-459f-4b47-a09f-6b121ae947da
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://devapi.crm.com/backoffice/v1/service_owner HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "terms_service": "https://www.crm.com/terms-and-conditions/",
    "privacy_policy": "https://www.crm.com/privacy-policy/"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "7cc1b26a-459f-4b47-a09f-6b121ae947da"
}
Get Service Owner Details
GET /service_owner

Returns the service owner details

Notes

Service Owner Details (configured by a “Service Owner” organisation) can be retrieved from every organisation within the business network (e.g. Businesses, Subsidiaries, Merchants)

Request parameters

cloud_name
string required

The organisation (service owner) cloud name

Example:
superpos

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
api_key
string optional

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Responses

200 200

The request has succeeded

Body
Object
public_key
string

The default (live) public key of the service owner

Example:
sdf3ref32rwerf324r134rw23rfd32r23r23r32r
organisation
Object

Details about the service owner organisation

id
string GUID

The organisation identifier

Example:
a47fb812-9d74-392c-ee52-443cc940e014
name
string

The organisation name

Example:
CRM.COM
cloud_name
string

The organisation cloud name

Example:
crmdotcom
terms_service
string

The terms of service URL

Example:
https://www.crm.com/terms-and-conditions/
privacy_policy
string

The privacy policy URL

Example:
https://www.crm.com/privacy-policy/
pricing_policy
string

The pricing policy URL

creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
default_service_id
string

The default service applied to each new contact that signs up and is added as a contact to the billing business.

billing_business_id
string

The billing business that will house all contacts and subscriptions that sign up via self sign up.

id
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_owner?cloud_name=crmdotcom HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "public_key": "sdf3ref32rwerf324r134rw23rfd32r23r23r32r",
    "organisation": {
        "id": "a47fb812-9d74-392c-ee52-443cc940e014",
        "name": "CRM.COM",
        "cloud_name": "crmdotcom"
    },
    "terms_service": "https://www.crm.com/terms-and-conditions/",
    "privacy_policy": "https://www.crm.com/privacy-policy/",
    "creatives": [
        {
            "id": "CA123456789AQWSXZAQWS1236547896541",
            "usage_type": "PROFILEIMAGE",
            "width": 2159,
            "height": 3075,
            "format": "jpg",
            "url": "https://assets.crm.com/image/logo.jpg",
            "public_id": "crm-com/image",
            "media": [
                {
                    "width": 200,
                    "height": 300,
                    "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                }
            ]
        }
    ]
}
Tags

Tags are unique identifiers that allow users to label records of an entity. This is to help simplify sorting and accessing records. Users can create and access tags for any of their records— Leads, Contacts, Service Requests etc.

POST /tags
PUT /tags/{id}
DELETE /tags/{id}
GET /tags
GET /tags/{id}
Create Tags
POST /tags

This operation creates tags for entities.

Request body

Object
name
string

Name of tag

Example:
Maintenance
description
string

Description of tag

Example:
This tag relates to maintenance issues
colour
string

The colour relating to the tag

Example:
75FG77
entity
string

The entity.

Enumeration:
SERVICE_REQUESTS
CONTACTS
LEADS
ACTIVITIES
PRODUCTS
Example 1
POST https://sandbox.crm.com/backoffice/v1/tags HTTP/1.1 

Content-Type: application/json

{
    "name": "Maintenance",
    "description": "This tag relates to maintenance issues",
    "colour": "75FG77",
    "entity": "CONTACTS"
}
Update Tag
PUT /tags/{id}

The following operation updates the tags for a specififc entity.

Path variables

id
string required

Id of the tag to be updated

Request body

Object
name
string

Name of the tag

Example:
Maintenance
description
string

Description of the tag

Example:
This tag depicts that some form of maintenance is required
colour
string

Colour relating to tag

Example:
HJGHJG86876876
state
string

State of tag

Enumeration:
ACTIVE
INACTIVE
Example 1
PUT https://sandbox.crm.com/backoffice/v1/tags/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "Maintenance",
    "description": "This tag depicts that some form of maintenance is required",
    "colour": "HJGHJG86876876",
    "state": "ACTIVE"
}
Delete Tag
DELETE /tags/{id}

This operation tags that have been created for an entity.

Path variables

id
string required

The id of the tag to be deleted.

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/tags/{id} HTTP/1.1 
List Tags
GET /tags

This process lists the entities with tags.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
sort
string

Defines on which attribute the results should be sorted.

Default:
CREATED_DATE
Example:
CREATED_DATE, NAME
order
string

Defines how the results will be ordered.

Default:
DESC
page
string

The page number that should be retrieved.

Example:
1
size
string

The size (total records) of each page.

Example:
5
Entity
string

The entity to filter by

Enumeration:
SERVICE_REQUESTS
LEADS
CONTACTS
PRODUCTS
ACTIVITIES
state
string

The state of the tag

Enumeration:
ACTIVE
INACTIVE

Responses

200 OK
Body
Object
content
Array
Object
id
string

The GUID of the tag.

Example:
GHFFSGD5464SFDSD
entity
string

The entity

Enumeration:
SERVICE_REQUESTS
LEADS
PRODUCTS
CONTACTS
ACTIVITIES
state
string

The state of the entity and the tags

Enumeration:
ACTIVE
INACTIVE
name
string

The name of the tag

Example:
Maintenance
description
string
colour
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/tags HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "sort": "CREATED_DATE, NAME",
    "order": "DESC",
    "page": "1",
    "size": "5"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "GHFFSGD5464SFDSD",
            "entity": "SERVICE_REQUESTS",
            "number_of_tags": 2,
            "state": "INACTIVE"
        }
    ]
}
Get Tag
GET /tags/{id}

Retrieves tag details for editing.

Path variables

id
string required

The tag id for editing purposes.

Responses

200 OK
Body
Object
entity
string

The enitity that the tag relates to.

Enumeration:
SERVICE_REQUESTS
LEADS
PRODUCTS
CONTACTS
ACTIVITIES
state
string

The state of the tag

Enumeration:
ACTIVE
INACTIVE
name
string

The name of the tag

Example:
Maintenance
description
string

Description of tag

Example:
Maintenance issues
colour
string

The colour of the tag

Example:
GF76HHH
Example 1
GET https://sandbox.crm.com/backoffice/v1/tags/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "entity": "PRODUCTS",
    "state": "INACTIVE",
    "name": "Maintenance",
    "description": "Maintenance issues",
    "colour": "GF76HHH"
}
Time Travel
PUT /time_travel/actions
GET /time_travel
Perform Time Travel Actions
PUT /time_travel/actions

Perform actions on the time travel utility tool

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
action
string required

The action to be performed

Enumeration:
START_AFRESH

Start the time travel utility tool by goind back to the origin time

TERMINATE

Terminate the time travel utility tool and return to the current time

TRAVEL_FORWARD

Travel forward in time and simulate system’s behavior

origin_time
integer epoch required nullable

The start time of the time travel utility tool (applicable and required when action is START_AFRESH)

Example:
1643629992
destination_time
integer epoch required nullable

The destination time to which the time travel utility tool is travelling forward. Should be between the “current” destination time and present time (applicable and required when action is TRAVEL_FORWARD)

Example:
1643630252

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
Example 2
Example 3

Start (Restart) the time travel utility tool by goind back to the origin time

PUT https://sandbox.crm.com/backoffice/v1/time_travel/actions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "action": "START_AFRESH",
    "origin_time": 1643629992
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42d4f83f-13ec-f4a2-ad1e-874788f4942b"
}

Travel forward in time and simulate system’s behavior

PUT https://sandbox.crm.com/backoffice/v1/time_travel/actions HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "action": "TRAVEL_FORWARD",
    "destination_time": 1643630252
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42d4f83f-13ec-f4a2-ad1e-874788f4942b"
}

Terminate the time machine feature and return to the current time

PUT https://sandbox.crm.com/backoffice/v1/time_travel/actions HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "action": "TERMINATE"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "42d4f83f-13ec-f4a2-ad1e-874788f4942b"
}
Get Time Travel
GET /time_travel

Get details of a specific time travel

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
origin_time
integer epoch

The start time of the time travel utility tool

Example:
1643629992
destination_time
integer epoch

The destination time to which the time travel utility tool is travelling forward. Should be between the “current” destination time and present time

Example:
1643630252
is_enabled
boolean

Defines whether time travel is enabled or not

Example:
true
status
string

The current status of time travel utility tool

Enumeration:
IN_PROGRESS

Time travel is in progress

SUCCESS

Time travel has succeeded

FAILURE

Time travel has failed

failure_reason
string

Details about why the time travel utility tool failed

Example:
Incorrect details
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/time_travel HTTP/1.1 

api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "origin_time": 1643629992,
    "destination_time": 1643630252,
    "is_enabled": "true",
    "status": "FAILURE",
    "failure_reason": "Incorrect details"
}
Rewards
GET /rewards_generic_settings
PUT /rewards_generic_settings
Get Reward Settings
GET /rewards_generic_settings

Update the generic reward settings for an organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
resolution_settings
Object

Details about resolution settings (which reward offers will award customers on their purchases)

resolution_method
string

Defines which reward offers will be provided

Enumeration:
ALL_MATCHED_OFFERS
BEST_OFFER_ACROSS_SCHEMES
BEST_OFFER_FROM_EACH_SCHEME
only_best_discount
boolean

Defines only if the best instant discount offer will be provided. Applicable only if the resolution method = ALL_MATCHED_OFFERs

Example:
true
restrict_awards
boolean

Defines whether awards will be restricted (not provided) when wallet (commerce) balance is spent

Example:
false
reduction_settings
Object

Details about back-end reduction settings

refund_type
Object

The refund financial transaction type that will be used for returning the reduced amount (spend) to the customers

id
string GUID

The refund financial transaction type identifier

Example:
a6984610-f1da-247d-83a9-a63f1c945391
name
string

The refund financial transaction type name

Example:
Back End Refund
refund_method
string

Defines how spend amount will be refunded to the contact

Enumeration:
SETTLE
PAYMENT_GATEWAY
integration
Object

Applicable only when back end reductions will be performed by a payment gateway integration

id
string

The unique identifier of the payment gateway integration

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The name of the payment gateway integration

Example:
Revolut
tier_settings
Object

Details about reward tiers

enable_tier
boolean

Defines whether reward tiers are supported or not

Example:
true
conversion_rate
integer

Defines the conversion rate between real currency and value units

Example:
1000
tier_evaluation
string

Defines the unit of time that tiering will be applied

Enumeration:
SIGN_UP_DATE
TIME_INTERVAL
tier_interval
integer

Defines the interval based on which customer will be advanced/downgraded to a tier

Example:
12
initial_month
string

The date when customers will be tiered for the first time

Enumeration:
JANUARY
FEBRUARY
MARCH
APRIL
MAY
JUNE
JULY
AUGUST
SEPTEMBER
OCTOBER
NOVEMBER
DECEMBER
auto_advance
boolean

Defines whether customers can advance to the next tier as soon as the next tier’s value units are reached

Example:
false
tiers
Array

Information about the reward tiers

Object
id
string GUID

The tier identifier

Example:
TIER001234543212345678UJIKY76HJR
name
string

The tier name

Example:
Gold
description
string

The tier description

Example:
Gold Customers
color
string

The tier color (used for marketing purposes)

Example:
#d4af37
value_units
integer

The tier value units (inclusive)

Example:
150000
creatives
Array
Object
id
string GUID

The creative identifier

Example:
CA123456789AQWSXZAQWS1236547896541
usage_type
string

Information about the creative type

Enumeration:
ATTACHMENT
PROFILEIMAGE
MARKETING
APPLE_LOCKSCREEN_ICON
APPLE_LOGO_IMAGE
APPLE_STRIP_IMAGE
GOOGLE_LOGO_IMAGE
GOOGLE_STRIP_IMAGE
LANDING_PAGE_LOGO_IMAGE
LANDING_PAGE_HEADER_IMAGE
LANDING_PAGE_BACKGROUND_IMAGE
HERO
LOGO
BACKGROUND
AVATAR
PARTNER_LOGO

Partner logos configurable by SO, applicable for Business, Merchant, Venue

DELIVERY_IMAGE

Applicable only for Applications

PICKUP_IMAGE

Applicable only for Applications

DIRECT_SALE_IMAGE

Applicable only for Applications

WALLET_IMAGE

Applicable only for Applications

LANDING_PAGE_IMAGE

Applicable only for Applications

APP_LOGO

Applicable only for Applications

CAROUSEL
width
integer

The creative width

Example:
2159
height
integer

The creative height

Example:
3075
format
string

The creative format

Example:
jpg
url
string

The creative content URL

Example:
https://assets.crm.com/image/logo.jpg
public_id
string

The creative public identifier

Example:
crm-com/image
media
Array

Information about the creative transformations

Object
width
integer

The transformed creative width

Example:
200
height
integer

The transformed creative height

Example:
300
url
string

The transformed creative URL

Example:
https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg
offer_restrictions_settings
Object

Details about reward offer restrictions settings

enable_restrictions
boolean

Defines whether reward offer restrictions is enabled or not

Example:
true
allowed_offer_types
Array of string

Defines the offer types that will be allowed to be created

Unique items: YES
Example:
[
    "MONETARY_DISCOUNT"
]
allowed_spend_methods
Array

Defines which spend methods are allowed

Unique items: YES
string
Enumeration:
INSTANT
ON_REQUEST
auto_spend_settings
Object

Defines the default automatic spend preferences for the organisation’s contacts

enabled
boolean

Defines whether spend preferences will be enabled on each new contact

Example:
true
wallet_amount
number

The default wallet balance that should be set on the contact spend preferences

Example:
0.01
purchase_amount
number

The default purchase amount that should be set on the contact spend preferences

Example:
0.01
purchase_match_settings
Object

Details about purchase events matching settings

mode
string

The mode that will be applied on purchase matching resolution

Enumeration:
NORMAL_MODE
TP_MODE
explicit_mode
Array

List of all organisations that will have different match mode

Object
organisation
Object

Details about the organisation from where such event was posted

id
string GUID

The organisation identifier

Example:
4248fab3-67d5-2eb1-eaf6-079ce18cd2ed
name
string

The organisation name

Example:
Bravo Coffee
purchased_products_matching
Object

Defines how purchased products will be matched (identified): against performed by organisation or not

is_enabled
boolean

Defines whether purchased product matching is enabled or not

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/rewards_generic_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "resolution_settings": {
        "resolution_method": "ALL_MATCHED_OFFERS",
        "only_best_discount": "true",
        "restrict_awards": "false"
    },
    "reduction_settings": {
        "refund_type": {
            "id": "QWERTY1234543212345678UJIKY76HMK",
            "name": "Back End Refund"
        },
        "refund_method": "PAYMENT_GATEWAY",
        "integration": {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "name": "Revolut"
        }
    },
    "tier_settings": {
        "enable_tier": "true",
        "conversion_rate": 1000,
        "tier_evaluation": "SIGN_UP_DATE",
        "tier_interval": 12,
        "initial_month": "JUNE",
        "auto_advance": "false",
        "tiers": [
            {
                "id": "TIER001234543212345678UJIKY76HJR",
                "name": "Gold",
                "description": "Gold Customers",
                "color": "#d4af37",
                "value_units": 150000,
                "creatives": [
                    {
                        "id": "CA123456789AQWSXZAQWS1236547896541",
                        "usage_type": "ATTACHMENT",
                        "width": 2159,
                        "height": 3075,
                        "format": "jpg",
                        "url": "https://assets.crm.com/image/logo.jpg",
                        "public_id": "crm-com/image",
                        "media": [
                            {
                                "width": 200,
                                "height": 300,
                                "url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "offer_restrictions_settings": {
        "enable_restrictions": "true",
        "allowed_offer_types": [
            ""
        ],
        "allowed_spend_methods": [
            "INSTANT"
        ]
    },
    "auto_spend_settings": {
        "enabled": "true",
        "wallet_amount": 0.01,
        "purchase_amount": 0.01
    }
}
Set Reward Settings
PUT /rewards_generic_settings

Update the generic reward settings for an organisation

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
resolution_settings
Object nullable

Details about resolution settings (which offers will award customers)

resolution_method
string required

Defines which reward offers will be provided

Enumeration:
ALL_MATCHED_OFFERS
BEST_OFFER_ACROSS_SCHEMES
BEST_OFFER_FROM_EACH_SCHEME
Default:
ALL_MATCHED_OFFERS
only_best_discount
boolean nullable

Defines only if the best instant discount offer will be provided. Applicable only if the resolution method = ALL_MATCHED_OFFERs

Example:
true
restrict_awards
boolean nullable

Defines whether awards will be restricted (not provided) when wallet (commerce) balance is spent

Default:
false
Example:
true
tier_settings
Object nullable

Details about reward tiers settings

enable_tier
boolean required

Defines whether reward tiers are supported

Example:
true
conversion_rate
integer nullable

Defines the conversion rate between real currency and value units

Default:
1000
Example:
1000
tier_evaluation
string nullable

Defines whether the period value units will be calculated based on customers sign up date or at a configurable interval (e.g. every 12 months)

Enumeration:
SIGN_UP_DATE
TIME_INTERVAL
Default:
SIGN_UP_DATE
tier_interval
integer nullable

Defines the interval based on which customer will be advanced/downgraded to a tier (Applicable only if the tier evaluation is based on time interval)

Default:
12
Example:
12
initial_month
string nullable

The first month when customers will be tiered for the first time (Applicable only if the tier evaluation is based on time interval)

Enumeration:
JANUARY
FEBRUARY
MARCH
APRIL
MAY
JUNE
JULY
AUGUST
SEPTEMBER
OCTOBER
NOVEMBER
DECEMBER
Default:
JANUARY
auto_advance
boolean required nullable

Defines whether customers can advance to the next tier as soon as the next tier’s value units are reached

Default:
false
Example:
true
tiers
Array required

Supported reward tiers

Min items: 1
Object
id
string GUID

The tier identifier

Example:
TIER001234543212345678UJIKY76HJR
name
string required

The tier name

Example:
Gold
description
string nullable

The tier description

Example:
Gold Customers
color
string required

The tier color (used for marketing purposes)

Example:
#d4af37
value_units
integer required

The tier value units (inclusive)

Example:
150000
media_group_id
string GUID

The tier related media group (identifier)

Example:
3ac1788d-cead-365b-25a5-9d0854c40c1f
reduction_settings
Object nullable

Details about back-end reduction settings

refund_type_id
string GUID nullable

The payout financial transaction type identifier

Default:
Back End Reduction Refund
Example:
REFUND1234543212345678UJIKY76HJR
refund_method
string nullable

Defines how spend amount will be refunded to the customer

Enumeration:
SETTLE
PAYMENT_GATEWAY
integration_id
string GUID

Applicable and required when back-end reduction will be performed by a payment gateway integration, e.g. Revolut

Example:
1f0e6842-3bec-2c82-e92e-a22d72ad3f15
offer_restrictions_settings
Object nullable

Details about reward offer restrictions settings

enable_restrictions
boolean required

Defines whether reward offer restrictions is enabled or not

Default:
false
Example:
false
allowed_offer_types
Array of string required

Defines the offer types that will be allowed to be created

Unique items: YES
Example:
[
    "MONETARY_DISCOUNT"
]
allowed_spend_methods
Array required

Defines which spend methods are allowed

Unique items: YES
Example:
[
    "INSTANT"
]
string
Enumeration:
ON_REQUESST
INSTANT
auto_spend_settings
Object nullable

Defines the default automatic spend preferences for the organisation’s contacts

enabled
boolean required

Defines whether spend preferences will be enabled on each new contact

Example:
true
wallet_amount
number nullable

The default wallet balance that should be set on the contact spend preferences

Example:
0.01
purchase_amount
number nullable

The default purchase amount that should be set on the contact spend preferences

Example:
0.01
purchase_match_settings
Object nullable

Details about purchase events matching settings

mode
string required

The mode that will be applied on purchase matching resolution

Enumeration:
NORMAL_MODE
TP_MODE
explicit_mode
Array nullable

List of all organisations that will have different match mode

Object
organisation_id
string GUID required

The organisation (identifier) that will have different match mode

Example:
3b21975a-e072-a6cc-c424-63d69ac9ef7e
purchased_products_matching
Object nullable

Defines how purchased products will be matched (identified): against performed by organisation or not

is_enabled
boolean nullable

Defines whether purchased product matching is enabled or not

Default:
false
Example:
true

Responses

200 200

Successful Request

Body
Object
id
string GUID

The organisation identifier

Example:
a6984610-f1da-247d-83a9-a63f1c945391
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/rewards_generic_settings HTTP/1.1 

Content-Type: application/json

{
    "resolution_settings": {
        "resolution_method": "ALL_MATCHED_OFFERS",
        "only_best_discount": "true",
        "restrict_awards": "true"
    },
    "tier_settings": {
        "enable_tier": "true",
        "conversion_rate": 1000,
        "tier_evaluation": "SIGN_UP_DATE",
        "tier_interval": 12,
        "initial_month": "JANUARY",
        "auto_advance": "true",
        "tiers": [
            {
                "id": "TIER001234543212345678UJIKY76HJR",
                "name": "Gold",
                "description": "Gold Customers",
                "color": "#d4af37",
                "value_units": 150000,
                "media_group_id": "3ac1788d-cead-365b-25a5-9d0854c40c1f"
            }
        ]
    },
    "reduction_settings": {
        "refund_type_id": "REFUND1234543212345678UJIKY76HJR",
        "refund_method": "PAYMENT_GATEWAY",
        "integration_id": ""
    },
    "offer_restrictions_settings": {
        "enable_restrictions": "false",
        "allowed_offer_types": [
            ""
        ],
        "allowed_spend_methods": [
            "ON_REQUESST"
        ]
    },
    "auto_spend_settings": {
        "enabled": "true",
        "wallet_amount": 0.01,
        "purchase_amount": 0.01
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a6984610-f1da-247d-83a9-a63f1c945391"
}
Security
PUT /security_settings
GET /security_settings
Set Security Settings
PUT /security_settings

Set the settings related to security (e.g. password policy)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
password_policy
Object

Details about back-end users password policy

password_expiration
Object nullable

Settings about password expiration

is_enabled
boolean required

Defines whether user passwords will be expired or not

Example:
true
period
integer required

Defines in how long password will be expired (in days)

Min: 14
Max: 730
Default:
90
Example:
15
notification
integer required

Defines in how long users will be notified for upcoming expired passwords (in days)

Default:
15
Example:
12
strong_password
Object nullable

Settings about strong password

is_contact_enabled
boolean required

Defines whether strong password will be required for contacts or not

Example:
false
is_user_enabled
boolean required

Defines whether strong password will be enhanced for users or not

Example:
false
user_policy
Object nullable

The explicit strong password policy for users

length
integer required

The minimum length that a password should have

Example:
12
concurrent_sessions_policy
Object

Details about maximum allowed concurrent sessions for Contacts and Users

is_enabled
boolean

Defines whether concurrent session policy will be applied

Default:
true
Example:
true
user_sessions
integer

Maximum allowed concurrent sessions for Users

Default:
3
Example:
3
two_factor_settings
Object

Details about two factor authentication

is_user_required
boolean required

Defines whether two factor authentication will be required for users or not

Example:
true
sso_settings
Object

Details about OIDC settings

is_enabled
boolean required

Defines whether OIDC is enabled or not

Example:
true
configuration_document_url
string nullable

The OIDC settings (e.g. oAuth redirection URL, scope) that will be used as part of the OIDC flow

Example:
azure.crm.com
application_id
string required nullable

The application (identifier) as configured in the OIDC provider (required if OIDC is enabled)

Example:
d6f9e2e8-2a57-4c54-4ee3-b0d8db840fde

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/security_settings HTTP/1.1 

Content-Type: application/json

{
    "password_policy": {
        "password_expiration": {
            "is_enabled": "true",
            "period": 15
        }
    },
    "concurrent_sessions_policy": {
        "is_enabled": "true",
        "contact_sessions": 3,
        "user_sessions": 3
    }
}
Get Security Settings
GET /security_settings

Retrieve the settings related to security (e.g. password policy)

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
password_policy
Object

Details about back-end users password policy

password_expiration
Object

Settings about password expiration

is_enabled
boolean

Defines whether user passwords will be expired or not

Example:
true
period
integer

Defines in how long password will be expired (in days)

Example:
15
notification
integer

Defines in how long users will be notified for upcoming expired passwords (in days)

Example:
12
strong_password
Object

Settings about strong password

is_contact_enabled
boolean

Defines whether strong password will be required for contacts or not

Example:
false
is_user_enabled
boolean

Defines whether strong password will be enhanced for users or not

Example:
true
user_policy
Object

The explicit strong password policy for users

length
integer

The minimum length that a password should have

Example:
12
concurrent_sessions_policy
Object

Details about maximum allowed concurrent sessions for Contacts and Users

is_enabled
boolean

Defines whether concurrent session policy will be applied

Example:
true
user_sessions
integer

Maximum allowed concurrent sessions for Users

Example:
3
sso_settings
Object

Details about OIDC settings

is_enabled
boolean

Defines whether OIDC is enabled or not

Default:
false
Example:
true
configuration_document_url
string

The OIDC settings (e.g. oAuth redirection URL, scope) that will be used as part of the OIDC flow

Example:
azure.crm.com
application_id
string

The application (identifier) as configured in the OIDC provider

Example:
d6f9e2e8-2a57-4c54-4ee3-b0d8db840fde
two_factor_settings
Object

Details about two factor authentication settings

is_user_required
boolean

Defines whether two factor authentication will be required for users or not

Example:
true
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/security_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "password_policy": {
        "password_expiration": {
            "is_enabled": true,
            "period": 15
        }
    },
    "concurrent_sessions_policy": {
        "is_enabled": "true",
        "contact_sessions": 3,
        "user_sessions": 3
    }
}
User Roles
POST /userroles
PUT /userroles/{id}
DELETE /userroles/{id}
GET /userroles
GET /userroles/{id}
Create User Role
POST /userroles

Create a user role

Notes

Only Service Owner users can create Owner roles or roles that can be used across child business network

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The user role name

Example:
Rewards Manager
description
string nullable

The user role description

Example:
Provide full access to rewards module
is_owner
boolean nullable

Defines whether the role will be used as the owner role on new sign ups

Example:
false
is_default
boolean nullable

Defines whether the role can be used across all child business network

Example:
false
permissions
Array required

The user role permissions

Min items: 1
Unique items: YES
string
Examples:
CONTACT_READCONTACT_WRITE

Responses

200 200

OK

Body
Object
id
string GUID

The user role identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST /userroles HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Rewards Manager",
    "description": "Provide full access to rewards module",
    "permissions": [
        "CONTACT_WRITE"
    ],
    "is_owner": "false",
    "is_default": "false"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Update User Role
PUT /userroles/{id}

Update an existing user role

Path variables

id
string GUID required

The user role (identifer) that will be updated

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

Only Service Owner users can update Owner roles or roles that can be used across child business network

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string nullable

The user role name

Example:
Rewards Manager
description
string nullable

The user role description

Example:
Provide full access to rewards module
is_owner
boolean nullable

Defines whether the role will be used as the owner role on new sign ups

Example:
false
is_default
string nullable

Defines whether the role can be used across all child business network

Example:
false
permissions
Array nullable

The user role permissions

Min items: 1
Unique items: YES
string
Examples:
CONTACT_READCONTACT_WRITE

Responses

200 200

OK

Body
Object
id
string GUID

The user role identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT /userroles/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

Content-Type: application/json
authorization: 4AD9C84FA60F9FE407140E20F707726A

{
    "name": "Rewards Manager",
    "description": "Provide full access to rewards module",
    "permissions": [
        "CONTACT_WRITE"
    ],
    "is_owner": "false",
    "is_default": "false"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}
Delete User Role
DELETE /userroles/{id}

Delete an existing user role

Path variables

id
string GUID required

The user role (identifer) that will be deleted

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Notes

Only Service Owner users can delete Owner roles or roles that can be used across child business network

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE /userroles/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 
List User Roles
GET /userroles

Search for user roles

Request parameters

name
string optional

The user role name

Example:
Rewards Manager
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
content
Array

Information related to admin user roles

Object
id
string GUID

The user role identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The user role name

Example:
Rewards Manager
description
string

The user role description

Example:
Provides full access on Rewards module
is_owner
string

Defines whether the role will be used as the owner role on new sign ups

Example:
false
is_default
string

Defines whether the role can be used across all child business network

Example:
true
is_full_access
boolean

Defines whether the role provides full access to all product areas

Example:
false
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET /userroles HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
            "name": "Rewards Manager",
            "description": "Provides full access on Rewards module",
            "is_owner": "false",
            "is_default": "true",
            "is_fullaccess": "false"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get User Role
GET /userroles/{id}

Get details for a single user role

Path variables

id
string GUID required

The user role (identifer) that will be retrieved

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

OK

Body
Object
id
string GUID

The user role identifier

Example:
CAD1E31269B76D7A65ACCE45B2E68DFD
name
string

The user role name

Example:
Rewards Manager
description
string

The user role description

Example:
Rewards module full access
permissions
Array

The user role permissions

Unique items: YES
Example:
[
    "CONTACT_READ",
    "CONTACT_WRITE"
]
string
Examples:
CONTACT_READCONTACT_WRITE
is_owner
string

Defines whether the role will be used as the owner role on new sign ups

Example:
false
is_default
string

Defines whether the role can be used across all child business network

Example:
true
is_full_access
boolean

Defines whether the role has full permissions

Example:
false
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://devapi.crm.com/backoffice/v1/userroles/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1 

authorization: 4AD9C84FA60F9FE407140E20F707726A

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
    "name": "Rewards Manager",
    "description": "Rewards module full access",
    "permissions": [
        "CONTACT_WRITE"
    ],
    "is_owner": "false",
    "is_default": "true",
    "is_full_access": "false"
}
Service Requests
GET /service_request_settings
PUT /service_request_settings
Get Service Request Settings
GET /service_request_settings

Get the generic settings of Service Requests

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
numbering_schemes
Array
Object
entity
string
Example:
SERVICE_REQUESTS
prefix
string
Example:
SR
starting_number
string
Example:
10001
number_of_digits
integer
Example:
5
last_number
string
Example:
SR10001
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/service_request_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "numbering_schemes": [
        {
            "entity": "SERVICE_REQUESTS",
            "prefix": "SR",
            "starting_number": "10001",
            "number_of_digits": 5,
            "last_number": "SR10001"
        }
    ]
}
Update Service Request Settings
PUT /service_request_settings

Update generic service request settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
numbering_schemes
Array
Object
entity
string
Example:
SERVICE_REQUESTS
prefix
string
starting_number
string
number_of_digits
integer
Example:
1

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/service_request_settings HTTP/1.1 

Content-Type: application/json

{
    "numbering_schemes": [
        {
            "entity": "SERVICE_REQUESTS",
            "prefix": "",
            "starting_number": "",
            "number_of_digits": 1
        }
    ]
}

HTTP/1.1 200 OK 
Queues
POST /queues
PUT /queues/{id}
GET /queues
GET /queues/{id}
DELETE /queues/{id}
DELETE /queues/{id}/queue_statuses/{status_id}
GET /queues/{id}/queue_statuses
Create Queue
POST /queues

Create a queue and it’s statuses to be used for service requests.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A unique name for the queue

Example:
Billing Issues
state
string

The state of the queue.

Example:
Active
statuses
Array
Object
name
string

The name of the queue status

Example:
Responded to customer
priority
string

The priority of the queue status

Example:
4
description
string

The description nof the queue status

Example:
Agent has responded to customer
color
string

The unique colour code relating to the status

Example:
#FAC8890
Examples

Responses

201 Created
Body
Object
id
string

The unique identifier of the newly created queue

Example:
V349C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 2
POST https://sandbox.crm.com/backoffice/v1/queues HTTP/1.1 

Content-Type: application/json

{
    "name": "Billing Issues",
    "state": "Active",
    "statuses": [
        {
            "name": "Responded to customer",
            "priority": "4",
            "description": "Agent has responded to customer",
            "color": "FAC8890"
        }
    ]
}
Update Queue
PUT /queues/{id}

Update a queue and it’s statuses to be used for service requests.

Path variables

id
string required

The GUID of nthe queue to be updated

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

A unique name for the queue

Example:
Billing Issues
state
string

The state of the queue

Enumeration:
INACTIVE
ACTIVE
statuses
Array

The queues’s statuses

Object
id
string

The GUID of the status

Example:
HJGJSHG78687HGFSHJ
name
string

Queues status name

Example:
Awaiting response
priority
string

The order of the status within the queue

Example:
4
description
string

The description of the status

Example:
The agent has responded to the customer
colour
string

The unique colour code for representing that status

Example:
#2C8EF8
Examples

Responses

200 OK
Body
Object
id
string

The unique identifier of the newly created queue

Example:
V349C84FA60F9FE407140E20F707726A
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 2
PUT https://sandbox.crm.com/backoffice/v1/queues/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

Content-Type: application/json

{
    "name": "Billing Issues",
    "state": "ACTIVE",
    "statuses": [
        {
            "id": "HJGJSHG78687HGFSHJ",
            "name": "Awaiting response",
            "priority": "4",
            "description": "The agent has responded to the customer",
            "colour": "2C8EF8"
        }
    ]
}
List Queues
GET /queues

Retrieve all queues

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for a queue using its name

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The GUID of the queue

Example:
74D9C84FA60F9FE407140E20F707726A
name
string

The name of the queue

Example:
Billing Issues
state
string

The life cycle state of the queue

Example:
Active
number_of_statuses
integer

Number of statuses that the queue comprises of

Example:
5
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/queues HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "74D9C84FA60F9FE407140E20F707726A",
            "name": "Billing Issues",
            "state": "Active",
            "number_of_statuses": 5
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Queue
GET /queues/{id}

Retrieve a queue and it’s statuses

Path variables

id
string GUID required

The GUID of the queue

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The GUID of the retrieved queue

name
string

The queue’s name

Example:
Billing Issues
state
string

The life cycle state of the queue

Example:
Active
statuses
Array

The queue’s statuses

Object
id
string GUID

Queue’s status GUID

Example:
6A24D2B5E44F44B28451FE021FCAD51E
name
string

Queue’s status name

Example:
Response submitted
priority
integer

The order of the status within the queue

Example:
5
description
string

The decsirption of the status

Example:
A response has been submitted to he customer - awaiting response
colour
string

The unique colour code of the status

Example:
#FA89CB
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/queues/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "",
    "name": "Billing Issues",
    "state": "Active",
    "statuses": [
        {
            "id": "6A24D2B5E44F44B28451FE021FCAD51E",
            "name": "Response submitted",
            "priority": 5,
            "description": "A response has been submitted to he customer - awaiting response",
            "colour": "FA89CB"
        }
    ]
}
Delete Queue
DELETE /queues/{id}

Delete a queue

Path variables

id
string required

The GUID of the queue to be deleted

Example:
74D9C84FA60F9FE407140E20F707726A

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/queues/74D9C84FA60F9FE407140E20F707726A HTTP/1.1 
Delete Queue Status Item
DELETE /queues/{id}/queue_statuses/{status_id}

DELETES a queues status

Path variables

id
string required

The GUID of the queues status to be deleted

Example:
PR90C84FA60F9FE407140E20F7077277
status_id
string required

The GUID of the queue status that all service requests should be transfered to.

Example:
JKHFJGFJDHG875873JHGJHG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
new_status_id
string

The new status id to transfer to.

Example:
JKGFSJHGJSHG7865JGHJFGHG

Responses

200 OK

The request has succeeded

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/queues/PR90C84FA60F9FE407140E20F7077277/queue_statuses/JKHFJGFJDHG875873JHGJHG HTTP/1.1 

Content-Type: application/json

{
    "new_status_id": "JKGFSJHGJSHG7865JGHJFGHG"
}
List Queue Statuses
GET /queues/{id}/queue_statuses

Retrieves all statuses defined for queues.

Path variables

id
string required

Queue id

Example:
KJHSJKHD

Request body

Object
sort
string

Defines on which attribute the results should be sorted.

order
string

How results will be sorted

page
integer

Page number that should be retreieved.

size
integer

The size of each page.

Responses

200 OK
Body
Object
content
Array
Object
id
string

id of the queue

Example:
KJHSDKJHDJKHS
name
string

name of queue status

Example:
Awaiting customer
queue
Object
id
string
name
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/queues/KJHSJKHD/queue_statuses HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "KJHSDKJHDJKHS",
            "name": "Awaiting customer",
            "queue": {
                "id": "",
                "name": ""
            }
        }
    ]
}
List Service Request Queue Statuses
GET /queue_statuses

Retrieves all statuses defined for queues.

Request parameters

name
string optional
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

id of the queue

Example:
KJHSDKJHDJKHS
name
string

name of queue status

Example:
Awaiting customer
queue
Object
id
string
name
string
description
string
priority
integer
color
string
Example 1
GET https://sandbox.crm.com/backoffice/v1/queue_statuses HTTP/1.1 

authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "KJHSDKJHDJKHS",
            "name": "Awaiting customer",
            "queue": {
                "id": "",
                "name": ""
            },
            "description": "",
            "priority": 1,
            "color": ""
        }
    ]
}
Priorities

Prioritisation model defines the required effort for responding and resolving a service request by the user. Set up the model to be used for assigning a priority number to an issue according to its urgency and impact.

PUT /priorities_model
GET /priorities_model
Update Priorities Model
PUT /priorities_model

Updates to the priorities model.

Request body

Object
priorities
Array
Object
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW

Responses

200 OK
Example 1
PUT https://sandbox.crm.com/backoffice/v1/priority_model HTTP/1.1 

Content-Type: application/json

{
    "priorities": [
        {
            "urgency": "LOW",
            "impact": "HIGH",
            "priority": "MEDIUM"
        }
    ]
}

HTTP/1.1 200 OK 
Get Priorities Model
GET /priorities_model

Retreives the priority model configured for this organisation

Request body

Object
impact
string
Enumeration:
HIGH
MEDIUM
LOW
urgency
string
Enumeration:
HIGH
MEDIUM
LOW

Responses

200 OK
Body
Object
priorities
Array
Object
id
string
Example:
JHJDGA76767
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW
colour
string

The colour relating to the priority.

Example:
87JG9H
Example 1
GET https://sandbox.crm.com/backoffice/v1/priorities_model HTTP/1.1 

Content-Type: application/json

{
    "impact": "HIGH",
    "urgency": "LOW"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "priorities": [
        {
            "id": "JHJDGA76767",
            "urgency": "LOW",
            "impact": "HIGH",
            "priority": "HIGH",
            "colour": "87JG9H"
        }
    ]
}
Service Request Categories

The following API’s relate to the abilioty to create categories and assign them to Service Requests.

POST /sr_categories
PUT /sr_categories/{id}
DELETE /sr_categories/{id}
Create Service Request Category
POST /sr_categories

This API creates a category for service requests to be assigned to.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

Name of category.

Example:
Maintenance
code
string

Unclear whether this is required.

descripion
string

The description of the category.

Example:
General Maintenance issues.
parent_id
string GUID

The id of the parent category.

Example:
HJSGJHGFJHSFu7678HSHGFD

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/sr_categories HTTP/1.1 

Content-Type: application/json

{
    "name": "Maintenance",
    "code": "",
    "descripion": "General Maintenance issues.",
    "parent_id": "HJSGJHGFJHSFu7678HSHGFD"
}
Update Service Request Category
PUT /sr_categories/{id}

This API updates a category for service requests to be assigned to.

Path variables

id
string GUID required

The id of the category to be updated.

Example:
JGDFJHGSFi7u7tJBSFHJG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

Name of category.

Example:
Maintenance
code
string

Unclear whether this is required.

descripion
string

The description of the category.

Example:
General Maintenance issues.
parent_id
string GUID

The id of the parent category.

Example:
HJSGJHGFJHSFu7678HSHGFD

Responses

201 Created
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/sr_categories/JGDFJHGSFi7u7tJBSFHJG HTTP/1.1 

Content-Type: application/json

{
    "name": "Maintenance",
    "code": "",
    "descripion": "General Maintenance issues.",
    "parent_id": "HJSGJHGFJHSFu7678HSHGFD"
}
Delete Service Request Categories
DELETE /sr_categories/{id}

This method deletes a category.

Path variables

id
string GUID required

The id of the category to be deleted.

Example:
JGSFJHGSHGuy7767JHGSHJFG

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/sr_categories/JGSFJHGSHGuy7767JHGSHJFG HTTP/1.1 
List Service Request Categories
GET /sr_categories

Return a list of service request categories.

Request parameters

parent_id
string optional

If specified, then all categories under the parent node will be returned. If not specified, then all root nodes of the tree are returned.

return_all
boolean optional

Returns all categories of the tree if set to True, ignoring parent_id and include_chid_nodes parameters

Default:
false
search_value
string optional

Search for a category based on name and description

description
string optional
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string GUID

The id of the category.

Example:
JGSJHGHSG7765MNSH
name
string

The name of the category

Example:
Physical Maintenance
code
string

unclear whether this is required.

description
string

The decsription of the category

Example:
General Maintenance issues.
child_nodes
integer

The number of child nodes.

Example:
2
parent
Object

Details pertaining to the parent of this category.

id
string GUID

The id of the parent category.

Example:
JKGSDJHGSiu7u6JHSDJKGH
name
string

The name of the parent category.

Example:
Maintenance
pages
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/sr_categories HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "JGSJHGHSG7765MNSH",
            "name": "Physical Maintenance",
            "code": "",
            "description": "General Maintenance issues.",
            "child_nodes": 2,
            "parent": {
                "id": "JKGSDJHGSiu7u6JHSDJKGH",
                "name": "Maintenance"
            }
        }
    ],
    "pages": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Alert times

The following methods will be used to set alert times for service requests.

PUT /queues/{id}/alerts
GET /queues/{id}/alerts/
Update Alert Times
PUT /queues/{id}/alerts

The following process updates alert times for a queue type.

Path variables

id
string required

The queue id

Request body

Object
content
Array
Object
priority
string

The priority relating to this alert.

Enumeration:
URGENT
HIGH
MEDIUM
LOW
time
integer

The unit of time relating to the alert time.

Example:
4
unit
string

The unit value relating to the alert time set.

Enumeration:
HOUR
DAY
WEEK
MONTH
MINUTE

Responses

201 Created
Body
Object
id
string GUID

The GUID of the queue type.

Example:
JKGFSJHGHJGHJS8789
Example 1
PUT https://sandbox.crm.com/backoffice/v1/alerts HTTP/1.1 

Content-Type: application/json

{
    "content": [
        {
            "queue_id": "KJSGFJHGHJFGSHGFS",
            "priority": "LOW",
            "time": 4,
            "unit": "DAYS"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "JKGFSJHGHJGHJS8789"
}
Get Alert times
GET /queues/{id}/alerts/

Retrieves the alert times set for a queue type.

Path variables

id
string required

The id of the queue type

Example:
JKHSFJHGHJFSGFJHG

Responses

200 OK
Body
Object
content
Array
Object
id
string

The id of the alert.

Example:
KJSGFJHGHJFGSHGFS
priority
string

The priority of the alert.

Enumeration:
URGENT
HIGH
MEDIUM
LOW
time
integer

The time relating to the alert set.

Example:
4
unit
string

The unit of time.

Enumeration:
HOUR
DAY
WEEK
MONTH
MINUTE
Example 1
GET https://sandbox.crm.com/backoffice/v1/alerts/JKHSFJHGHJFSGFJHG HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "KJSGFJHGHJFGSHGFS",
            "priority": "URGENT",
            "time": 4,
            "unit": "MONTHS"
        }
    ]
}
Approximate closure times

These methods will allow the user to set approximate closure times for service requests.

PUT /queues/{id}/approx_close_times
GET /queues/{id}/approx_close_times
Update Closure Times
PUT /queues/{id}/approx_close_times

The following process updates approximate closure times for a queue type.

Path variables

id
string required

The GUID of the queue type

Request body

Object
content
Array
Object
priority
string

The priority relating to this closure time.

Enumeration:
URGENT
HIGH
MEDIUM
LOW
time
integer

The unit of time relating to the closure time.

Example:
4
unit
string

The unit value relating to the closure time set.

Enumeration:
MINUTE
HOUR
DAY
WEEK
MONTH

Responses

201 Created
Body
Object
id
string GUID

The GUID of the queue type.

Example:
JKGFSJHGHJGHJS8789
Example 1
PUT https://sandbox.crm.com/backoffice/v1/queues/{id}/approx_close_times HTTP/1.1 

Content-Type: application/json

{
    "content": [
        {
            "priority": "HIGH",
            "time": 4,
            "unit": "MONTH"
        }
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "JKGFSJHGHJGHJS8789"
}
Get Closure Times
GET /queues/{id}/approx_close_times

Retrieves the approximate close times times set for a queue type.

Path variables

id
string required

The id of the queue type

Example:
JKHSFJHGHJFSGFJHG

Responses

200 OK
Body
Object
content
Array
Object
id
string

The id of the close time.

Example:
KJSGFJHGHJFGSHGFS
priority
string

The priority relating to the close time.

Enumeration:
URGENT
HIGH
MEDIUM
LOW
time
integer

The time relating to the close time set.

Example:
4
unit
string

The unit of time.

Enumeration:
HOURS
DAYS
WEEKS
MONTHS
MINUTE
Example 1
GET https://sandbox.crm.com/backoffice/v1/queues/JKHSFJHGHJFSGFJHG/approx_close_times HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "KJSGFJHGHJFGSHGFS",
            "priority": "LOW",
            "time": 4,
            "unit": "WEEKS"
        }
    ]
}
Closure Reasons

The following API’s relate to the ability to configure closure reasons for Service Requests

POST /closure_reasons
PUT /closure_reason/{id}
GET /closure_reasons
DELETE /closure_reasons/{id}
Create Closure Reasons
POST /closure_reasons

Creates specific closure reasons for service requests

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
closure_reason
Object
name
string
description
string
Example 1
POST https://sandbox.crm.com/backoffice/v1/closure_reasons HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "closure_reason": {
        "name": "",
        "description": ""
    }
}
Update Closure Reasons
PUT /closure_reason/{id}

Creates specific closure reasons for service requests

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string required

The public api key required for API calls to identify the organisation

Example:
8c54d563-b991-4b76-8a83-557c08166f95

Request body

Object
closure_reason
Object
name
string

name of reason

Example:
reffered
description
string

description of the reason

Example:
reffered to technical consultant
Example 1
PUT https://sandbox.crm.com/backoffice/v1/closure_reason HTTP/1.1 

api_key: 8c54d563-b991-4b76-8a83-557c08166f95
Content-Type: application/json

{
    "closure_reason": {
        "id": "",
        "name": "reffered",
        "description": "reffered to technical consultant"
    }
}
Get Closure Reasons
GET /closure_reasons

Retrieves all closure reasons configured for service requests.

Responses

200 OK
Body
Object
content
Array
Object
id
string

The id of the closure reason

name
string

The name of the closure reason

Example:
Reffered to installer
description
string

The description of the closure reason

Example:
This service request is handed over to installation team.
Example 1
GET https://sandbox.crm.com/backoffice/v1/closure_reasons HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "name": "Reffered to installer",
            "description": "This service request is handed over to installation team."
        }
    ]
}
Delete Closure Reason
DELETE /closure_reasons/{id}

Deletes a clousre reason.

Path variables

id
string required
Self Service

The ability to define certain requirements for the ability to create service requests from self service platforms.

PUT /queues/{id}/application_setting
GET /queues/{id}/application_setting
Update Self Service Settings
PUT /queues/{id}/application_setting

The ability to create self service settings for service requests

Path variables

id
string required

queue id

Request body

Object
state
string required

Whether self service creation of service requests is enabled or disabled for use on self service platforms.

Enumeration:
ENABLED
DISABLED
clasification
string

The classification name to be displayed on the self service platform for this queue. Required if state = ENABLED.

Example:
Billing Issues
owner
Object

The user that is defined as the resource/owner of all service requests created from self service for this queue. Required if ENABLED.

id
string

The id of the user or team of users.

Example:
JHDKJHDKJHDA
name
string

The name of the user or team

Example:
John Smith
default_priority
Object

The default priority set for all service requests created for this queue type from self service.Required if ENABLED.

urgency
string
Enumeration:
HIGH
MEDIUM
LOW
impact
string
Enumeration:
HIGH
MEDIUM
LOW
tags
Array of string

List of tags that shall be added to every service request created from self service. This is optional when ENABLED. This can not be defined when DISABLED.

Example 1
PUT https://sandbox.crm.com/backoffice/v1/queues/{id}/application_setting HTTP/1.1 

Content-Type: application/json

{
    "state": "DISABLED",
    "clasification": "Billing Issues",
    "owner": {
        "id": "JHDKJHDKJHDA",
        "name": "John Smith"
    },
    "default_priority": {
        "urgency": "LOW",
        "impact": "LOW"
    },
    "tags": [
        {
            "id": "KJHSKJHDKJSHDKJSH"
        }
    ]
}
Get Self Service Settings
GET /queues/{id}/application_setting

Retrieves the self service settings configured for specific queue type.

Path variables

id
string required

Responses

200 OK
Body
Object
state
string

The satate of whether this queue type is enabled for use on self service

Enumeration:
ENABLED
DISABLED
classification
string

The classification name to be displayed on the self service platform for this queue. Required if state = ENABLED.

Example:
Billing Issues
owner
Object

details relating to the owner that is assigned to all service requests that are created from self service for that specified queue type.

id
string
Example:
JHDKJHDKJHDA
name
string
Example:
John Smith
default_priority
Object

priority relating to the priority that is assigned to all service requests that are created from self service for that specified queue type.

impact
string
Enumeration:
HIGH
MEDIUM
LOW
urgency
string
Enumeration:
HIGH
MEDIUM
LOW
priority
string
Enumeration:
URGENT
HIGH
MEDIUM
LOW
tags
Array of string

All tags that should be added to a service request that are created from self service platforms for a specified queue type relating to a classification selected by the contact.

Example 1
GET https://sandbox.crm.com/backoffice/v1/queues/{id}/application_setting HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "state": "ENABLED",
    "classification": "Billing Issues",
    "owner": {
        "id": "JHDKJHDKJHDA",
        "name": "John Smith"
    },
    "default_priority": {
        "impact": "MEDIUM",
        "urgency": "MEDIUM",
        "priority": "MEDIUM"
    },
    "tags": [
        {
            "id": "KJHSKJHDKJSHDKJSH"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "state": "ENABLED",
    "classification": "Billing Issues",
    "owner": {
        "id": "JHDKJHDKJHDA",
        "name": "John Smith"
    },
    "default_priority": {
        "impact": "MEDIUM",
        "urgency": "HIGH",
        "priority": "URGENT"
    },
    "tags": [
        {
            "id": "KJHSKJHDKJSHDKJSH"
        }
    ]
}
Subscriptions
GET /subscription_settings
PUT /subscription_settings
GET /billing_settings
PUT /billing_settings
Get Subscription Settings
GET /subscription_settings

Retrieve Subscription Settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
automatic_deactivations
Object

Defines the deactivation process’s behaviour

deactivation_method
string required

Defines when the actual deactivation of a service will be performed by also considering the day and time at which the service was activated.

Enumeration:
BASED_ON_DAY

Deactivation will be performed during the day, regardless of the time the service was activated

BASED_ON_DAY_AND_HOUR

Deactivation will be performed be also considering the time at which the service was activated. Service is deactivated only afte rthis time of day

Default:
BASED_ON_DAY
Example:
BASED_ON_DAY
automatic_cancellations
Object

Defines the automatic cancellation process’s behaviour. Services being deactivated longer than the specified minimum period of time will be automatically cancelled.

minimum_period
integer required

The minimum deactivation period of time duration

Example:
3
uot
string required

The unit of time for the minimum deactivation period.

Enumeration:
DAYS
MONTHS
Default:
MONTHS
out_of_contract_cancellation
Object

Rules that describe when a subscriber is allowed to request for a cancellation of services when these are not in contract (contract period ended or service was never in contract).

allow_cancellation
string required

Settings on when the cancellation is allowed. Once must be specified

Enumeration:
ON_NOTICE

Requires a notice period befor cancellation

IMMEDIATELY

Immediate cancellation allowed

ON_NEXT_BILLING_CYCLE

Cancellation allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

Default:
IMMEDIATELY
notice_period
Object

Applicable and required only if cancellation is allowed On notice

duration
string required

The notice period’s duration

Example:
1
uot
string required

The notice period unit of time

Enumeration:
DAYS
MONTHS
Default:
DAYS
Example:
MONTHS
in_contract_cancellation
Object

Rules that describe when a subscriber is allowed to request for a cancellation of services when these are still in contract.

allow_cancellation
string required

Settings on when the cancellation is allowed. Once must be specified

Enumeration:
IMMEDIATELY

Immediate cancellation allowed

ON_CONTRACT_END_DATE

Cancellation allowed only after the cotnract end date (from the contract end date - inclusive - and onwards)

ON_NEXT_BILLING_CYCLE

Cancellation allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

Default:
IMMEDIATELY
regret
Object

Rules that describe when a subscriber is allowed to request for a regret. If specified then a service can be regretted only X period after its purchase. After this period the service cannot be regretted, but it should be cancelled.

allow_regret
boolean required

Define whether service regret is allowed or not. If the business does not want to allow service regret, then it should be set to False. If allowed, then a period should be specified

Default:
false
Example:
true
regret_period
integer required nullable

Define when a service regret is allowed, e.g. 14 days after its activation . Mandatory if regret is allowed

Example:
14
uot
string required nullable

The regret period’s unit of time.Mandatory if regret is allowed

Enumeration:
DAYS
MONTHS
Default:
DAYS
Example:
DAYS
starting_from
string required nullable

The date after which the allowed regret period is calculated. MAndatory if regret is allowed.

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE
Default:
SERVICE_FIRST_EFFECTIVE_DATE
Example:
SERVICE_FIRST_EFFECTIVE_DATE
paused_period
Object

Rules that describe how often and for long a contact can request a service pause. If no rules are specified, then no restrictions are applied when pausing a service.

days_per_year
Object nullable

How many days per year a service can be paused.

allowed_days
integer required

Maximum allowed number of days that a service can be paused within a year

Example:
30
year_starting_from
string required

Definition of the what is a “year” which maps to the service’s first activation date

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE

The service’s first activation date

Default:
SERVICE_FIRST_EFFECTIVE_DATE
Example:
SERVICE_FIRST_EFFECTIVE_DATE
times_per_year
Object nullable

How many times per year a service can be paused.

allowed_times
integer required

How many times within a year a service can be paused (regardless of each paused period’s duration)

Example:
3
year_starting_from
string required

Definition of the what is a “year”, i.e. if it’s the calencar year or a year starting from a service’s milestone like its activation date

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE

The service’s first activation date

Default:
SERVICE_FIRST_EFFECTIVE_DATE
Example:
SERVICE_FIRST_EFFECTIVE_DATE
days_per_pause
Object nullable

Restriction on the number of days for each paused period, i.e. everytime that a service is paused, the paused period will have a minimum and a maximum allowed duration. At least one of the tw settings must be specified.

minimum
integer nullable

The mininum number of days per paused period

Example:
3
maximum
integer nullable

The maximuum number of days per paused period

Example:
30
service_changes
Array

Rules that describe when a subscriber is allowed to request for a service change. A rule per service change type is allowed.

Object
change_type
string required

The service change type.

Enumeration:
UPGRADE
DOWGRADE
SWITCH
Example:
UPGRADE
allow_change
string required

Settings on when the service change is allowed. Once must be specified

Enumeration:
IMMEDIATELY

Immediate serice change is allowed

ON_NEXT_BILLING_CYCLE

Service change is allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

ON_CONTRACT_END_DATE

Service change is allowed only after the contract end date (from the cotnract end date - inclusive - and onwards)

Default:
IMMEDIATELY
Example:
ON_NEXT_BILLING_CYCLE
service_restrictions
Array

Rules that define the maximum number of services that a customer can subscribe to. Multiple rules can be specified but they have to be unique i.e. refer to different classification of account.

Object
maximum_services
integer required

Maximum number of services that a customer can subscribed to

Example:
5
account_classification
Object

The account classification of the customer. If specified, then restrictions are applied only to these customers.

id
string

The account classification’s unique identifier

name
string

The account classification’s name

activation_rule
Object

Rule that determines if and when a service can remain Effective or it’s eligible to move into the Effective state

threshold
number

Account oustanding amount threshold. Service is eligible to go into Effective state if the oustanding amount is less than or equal to the threshold. If not specified, it defaults to 0. Always set in the business’s base currency

Example:
0.01
currency_code
string
Example:
EUR
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/subscription_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "automatic_deactivations": {
        "deactivation_method": "BASED_ON_DAY"
    },
    "automatic_cancellations": {
        "minimum_period": 3,
        "uot": "MONTHS"
    },
    "out_of_contract_cancellation": {
        "allow_cancellation": "IMMEDIATELY",
        "notice_period": {
            "duration": "1",
            "uot": "MONTHS"
        }
    },
    "in_contract_cancellation": {
        "allow_cancellation": "IMMEDIATELY"
    },
    "regret": {
        "allow_regret": "true",
        "regret_period": 14,
        "uot": "DAYS",
        "starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
    },
    "paused_period": {
        "days_per_year": {
            "allowed_days": 30,
            "year_starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
        },
        "times_per_year": {
            "allowed_times": 3,
            "year_starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
        },
        "days_per_pause": {
            "minimum": 3,
            "maximum": 30
        }
    },
    "service_changes": [
        {
            "change_type": "UPGRADE",
            "allow_change": "ON_NEXT_BILLING_CYCLE"
        }
    ],
    "service_restrictions": [
        {
            "maximum_services": 5,
            "account_classification": {
                "id": "",
                "name": ""
            }
        }
    ],
    "activation_rule": {
        "threshold": 0.01,
        "currency_code": "EUR"
    }
}
Update Subscription Settings
PUT /subscription_settings

Updates the settings related to subscriptions

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
automatic_deactivations
Object required

Defines the deactivation process’s behaviour

deactivation_method
string required

Defines when the actual deactivation of a service will be performed by also considering the day and time at which the service was activated.

Enumeration:
BASED_ON_DAY

Deactivation will be performed during the day, regardless of the time the service was activated

BASED_ON_DAY_AND_HOUR

Deactivation will be performed be also considering the time at which the service was activated. Service is deactivated only afte rthis time of day

Default:
BASED_ON_DAY
Example:
BASED_ON_DAY
automatic_cancellations
Object

Defines the automatic cancellation process’s behaviour. Services being deactivated longer than the specified minimum period of time will be automatically cancelled.If not specified, the automatic cancelledaitons are disabled.

minimum_period
integer required

The minimum deactivation period of time duration

Example:
3
uot
string required

The unit of time for the minimum deactivation period.

Enumeration:
DAYS
MONTHS
out_of_contract_cancellation
Object

Rules that describe when a subscriber is allowed to request for a cancellation of services when these are not in contract (contract period ended or service was never in contract).

allow_cancellation
string required

Settings on when the cancellation is allowed. Once must be specified

Enumeration:
IMMEDIATELLY

Immediate cancellation allowed

ON_NOTICE

Requires a notice period befor cancellation

ON_NEXT_BILLING_CYCLE

Cancellation allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

Default:
IMMEDIATELLY
notice_period
Object required nullable

Applicable and required only if cancellation is allowed On notice

duration
string required

The notice period’s duration

uot
string required

The notice period’s unit of time

Enumeration:
DAYS
MONTHS
Default:
DAYS
Example:
DAYS
in_contract_cancellation
Object

Rules that describe when a subscriber is allowed to request for a cancellation of services when these are still in contract.

allow_cancellation
string required

Settings on when the cancellation is allowed. Once must be specified

Enumeration:
IMMEDIATELLY

Immediate cancellation allowed

ON_CONTRACT_END_DATE

Cancellation allowed only after the cotnract end date (from the contract end date - inclusive - and onwards)

ON_NEXT_BILLING_CYCLE

Cancellation allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

Default:
IMMEDIATELLY
Example:
ON_NEXT_BILLING_CYCLE
regret
Object

Rules that describe when a subscriber is allowed to request for a regret. If specified then a service can be regretted only X period after its purchase. After this period the service cannot be regretted, but it should be cancelled.

allow_regret
boolean required

Define whether service regret is allowed or not. If the business does not want to allow service regret, then it should be set to False. If allowed, then a period should be specified

Default:
false
Example:
true
regret_period
integer required nullable

Define when a service regret is allowed, e.g. 14 days after its activation . Mandatory if regret is allowed

Example:
14
uot
string

The regret period’s unit of time.Mandatory if regret is allowed

Enumeration:
DAYS
MONTHS
Default:
DAYS
Example:
DAYS
starting_from
string required nullable

The date after which the allowed regret period is calculated. MAndatory if regret is allowed.

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE
Default:
SERVICE_FIRST_EFFECTIVE_DATE
Example:
SERVICE_FIRST_EFFECTIVE_DATE
paused_period
Object

Rules that describe how often and for long a customer can request a service pause. If no rules are specified, then no restrictions are applied when pausing a service.

days_per_year
Object nullable

How many days per year a service can be paused.

allowed_days
integer required

Maximum allowed number of days that a service can be paused within a year

Example:
30
year_starting_from
string required

Definition of the what is a “year”, i.e. if it’s the calencar year or a year starting from a service’s milestone like its activation date

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE

The service’s first activation date

Default:
SERVICE_FIRST_EFFECTIVE_DATE
Example:
SERVICE_FIRST_EFFECTIVE_DATE
times_per_year
Object nullable

How many times per year a service can be paused.

allowed_times
integer required

How many times within a year a service can be paused (regardless of each paused period’s duration)

Example:
3
year_starting_from
string required

Definition of the what is a “year” which maps to the service’s first activation date

Enumeration:
SERVICE_FIRST_EFFECTIVE_DATE

The service’s first activation date

Example:
SERVICE_FIRST_EFFECTIVE_DATE
days_per_pause
Object nullable

Restrction on the number of days for each paused period, i.e. everytime that a service is paused, the paused period will have a minimum and a maximum allowed duration. At least one of the two settings must be specified.

minimum
integer nullable

The mininum number of days per paused period

Example:
1
maximum
integer nullable

The maximum number of days per paused period

Example:
5
service_changes
Array

Rules that describe when a subscriber is allowed to request for a service change. A rule per service change type is allowed.

Object
change_type
string required

Service change type

Enumeration:
UPGRADE
DOWNGRADE
SWITCH
Example:
UPGRADE
allow_change
string required

Settings on when the service change is allowed. Once must be specified

Enumeration:
IMMEDIATELLY

Immediate serice change is allowed

ON_NEXT_BILLING_CYCLE

Service change is allowed only after the next billing cycle (from the next billing cycle’s start date - inclusive - and onwards)

ON_CONTRACT_END_DATE

Service change is allowed only after the contract end date (from the cotnract end date - inclusive - and onwards)

Default:
IMMEDIATELLY
service_restrictions
Array

Rules that define the maximum number of services that a customer can subscribe to. Multiple rules can be specified but they have to be unique i.e. refer to different classification of account.

Object
maximum_services
integer

Maximum number of services that a customer can subscribed to

Example:
5
account_classification_id
string

The account classification of the customer. If specified, then restrictions are applied only to these customers.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
activation_rule
Object

Rule that determins if and when a service can remain Effective or it’s eligible to move into the Effective state

threshold
number

Account oustanding amount threshold. Service is eligible to go into Effective state if the oustanding amount is less than or equal to the threshold. If not specified, it defaults to 0. Always set in the business’s base currency

Example:
0.01

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/subscription_settings HTTP/1.1 

Content-Type: application/json

{
    "automatic_deactivations": {
        "deactivation_method": "BASED_ON_DAY"
    },
    "automatic_cancellations": {
        "minimum_period": 3,
        "uot": "MONTHS"
    },
    "out_of_contract_cancellation": {
        "allow_cancellation": "IMMEDIATELLY",
        "notice_period": {
            "duration": "",
            "uot": "DAYS"
        }
    },
    "in_contract_cancellation": {
        "allow_cancellation": "ON_NEXT_BILLING_CYCLE"
    },
    "regret": {
        "allow_regret": true,
        "regret_period": 14,
        "uot": "DAYS",
        "starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
    },
    "paused_period": {
        "days_per_year": {
            "allowed_days": 30,
            "year_starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
        },
        "times_per_year": {
            "allowed_times": 3,
            "year_starting_from": "SERVICE_FIRST_EFFECTIVE_DATE"
        },
        "days_per_pause": {
            "minimum": 1,
            "maximum": 5
        }
    },
    "service_changes": [
        {
            "change_type": "UPGRADE",
            "allow_change": "IMMEDIATELLY"
        }
    ],
    "service_restrictions": [
        {
            "maximum_services": 5,
            "account_classification_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
        }
    ],
    "activation_rule": {
        "threshold": 0.01
    }
}

HTTP/1.1 200 OK 
Get Billing Settings
GET /billing_settings

Retrieve general billing settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
calendar_billing
Object

Calendar billing defines whether subscribers will be billed on their services’ Annniversary or on a specific Period. In the first case, service is billind on its urchase Anniversay day of month, in the case of PEriod billing, all services among all subscribers are billing on a defined day of month

type
string required

Applies Anniversary or Period Billing

Enumeration:
ANNIVERSARY
PERIOD
Default:
ANNIVERSARY
Example:
ANNIVERSARY
billing_day
integer required nullable

Applicable and mandatory for Period billing. this is the day of month from which all services will be billed

Example:
1
additional_billable_states
Object

By default services are billed only for the Effective period. This list includes any other service states which are additinally billable

service_states
Array
Min items: 1
Example:
["NOT_EFFECTIVE"]
string
Enumeration:
NOT_EFFECTIVE
PAUSED
services
Array

List of services for which the additional billable states are applied. If not specified, then all services will be additionally billed. Only termed services can be specified

Object
id
string

The service product’s identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
sku
string

Product SKU

Example:
TV002
name
string

Product name

Example:
TV Service
non_creditable_states
Object

A set of subscription service life cycle states that will be considered as non creditable ones during billing. By default, only the Draft and Effective life cycle states are considered as non creditable

service_states
Array
Min items: 1
Example:
["NOT_EFFECTIVE"]
string
Enumeration:
NOT_EFFECTIVE
PAISED
CANCELLED
services
Array

List of services for which the non-creditable states are applied. If not specified, then all services will not be credited. Only termed services can be specified

Object
id
string

The service product’s identifier

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
sku
string

The product’s SKU

Example:
TV001
name
string

The product’s name

Example:
TV Service
rating
Object

Defines billing rules on when and how services will be billed

bill_in_advance
Object

By default, services are billed on their billing day of month. If this settng is specified, then servces can be billed in advance a specific period prior the next billing cycle begins

period
integer required

The period’s value

Example:
3
uot
string required

The period’s unit of time

Enumeration:
DAYS
MONTHS
Default:
DAYS
Example:
DAYS
prorate_period
Object

Specifies whether sevice’s billing will be prorated or not

enabled
boolean required

Enable service proration

Default:
false
Example:
true
threshold_day
integer required

The day of month used as a threshold to deide whether the service is prorated or not. If service is purchased prior this day, then the service is not prorated. Required if proratng is enabled

Example:
15
invoicing
Object

Defines how invoices and/or credit notes will be generated during recurring billing. If not specified, then the default financial transaction types are used.

invoice_type
Object

The Invoie financial transaction’s type

id
string
Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string
Example:
Invoice
credit_note_type
Object

The Credit Note’s financial transaction’s type

id
string
Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e
name
string
Example:
Credit Note
usage_billing
Object

Usage Billing Settings

verify_allowance
boolean

Defines whether usage allowance is verified when a usage record is processed or not. If set to True, then usage record is posted only if there’s remaining allowance enough to cover the record’s usage amount, otherwise it gets Rejected. If set to False, then remaining allowance is not verified on posting the record.

Example:
true
default_service
Object

The default product assigned to business when signing up. Available only for then a Billing Business used in the SaaS model

id
string

The unique identifer of the product

Example:
5cc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The name of the product

Example:
Try It
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/billing_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "calendar_billing": {
        "type": "ANNIVERSARY",
        "billing_day": 1
    },
    "additional_billable_states": {
        "service_states": [
            "NOT_EFFECTIVE"
        ],
        "services": [
            {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "sku": "TV002",
                "name": "TV Service"
            }
        ]
    },
    "non_creditable_states": {
        "service_states": [
            "NOT_EFFECTIVE"
        ],
        "services": [
            {
                "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                "sku": "TV001",
                "name": "TV Service"
            }
        ]
    },
    "rating": {
        "bill_in_advance": {
            "period": 3,
            "uot": "DAYS"
        },
        "prorate_period": {
            "enabled": true,
            "threshold_day": 15
        }
    },
    "invoicing": {
        "invoice_type": {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "name": "Invoice"
        },
        "credit_note_type": {
            "id": "3dc0809f-ed91-4b68-b912-5bd6064d901e",
            "name": "Credit Note"
        }
    },
    "usage_billing": {
        "verify_allowance": "true"
    },
    "default_service": {
        "id": "5cc0809f-ed91-4b68-b912-5bd6064d901e",
        "name": "Try It"
    }
}
Update Billing Settings
PUT /billing_settings

Update general billing settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
calendar_billing
Object

Calendar billing defines whether subscribers will be billed on their services’ Annniversary or on a specific Period. In the first case, service is billind on its urchase Anniversay day of month, in the case of PEriod billing, all services among all subscribers are billing on a defined day of month

type
string required

Applies Anniversary or Period Billing

Enumeration:
ANNIVERSARY
PERIOD
Default:
ANNIVERSARY
Example:
ANNIVERSARY
billing_day
integer

Applicable and mandatory for Period billing. this is the day of month from which all services will be billed

Example:
1
additional_billable_states
Object

By default services are billed only for the Effective period. This list includes any other service states which are additinally billable

service_states
Array
Example:
["NOT_EFFECTIVE"]
string
Enumeration:
NOT_EFFECTIVE
PAUSED
services
Array

List of services that will be additionally billed during the specified states. Only termed service products can be specified

Unique items: YES
string
Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
non_creditable_states
Object

A set of subscription service life cycle states that will be considered as non creditable ones during billing. By default, only the Draft and Effective life cycle states are considered as non creditable

service_states
Array
Example:
["NOT_EFFECTIVE"]
string
Enumeration:
NOT_EFFECTIVE
PAUSED
CANCELLED
services
Array

List of service products identifier that will not be credtied during the specified states. Only termed service products can be specified

Unique items: YES
string
Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
rating
Object

Defines billing rules on when and how services will be billed

bill_in_advance
Object

By default, services are billed on their billing day of month. If this settng is specified, then servces can be billed in advance a specific period prior the next billing cycle begins

period
integer required

The period’s value

Example:
3
uot
string required

The period’s unit of time

Enumeration:
DAYS
MONTHS
Example:
DAYS
prorate_period
Object

Specifies whether sevice’s billing will be prorated or not

enabled
boolean required

Enable service proration

Default:
false
Example:
true
threshold_day
integer

The day of month used as a threshold to deide whether the service is prorated or not. If service is purchased prior this day, then the service is not prorated. Required if proratng is enabled

Example:
15
invoicing
Object

Defines how invoices and/or credit notes will be generated during recurring billing. If not specified, then the default financial transaction types are used.

invoice_type_id
string

The invoice type’s unique identifier

credit_note_type_id
string

The credit note type’s unique identifier

usage_billing
Object

Usage Billing Settings

verify_allowance
boolean

Defines whether usage allowance is verified when a usage record is processed or not. If set to True, then usage record is posted only if there’s remaining allowance enough to cover the record’s usage amount, otherwise it gets Rejected. If set to False, then remaining allowance is not verified on posting the record.

Example:
true

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/billing_settings HTTP/1.1 

Content-Type: application/json

{
    "calendar_billing": {
        "type": "ANNIVERSARY",
        "billing_day": 1
    },
    "additional_billable_states": {
        "service_states": [
            "NOT_EFFECTIVE"
        ],
        "services": [
            "4dc0809f-ed91-4b68-b912-5bd6064d901e"
        ]
    },
    "non_creditable_states": {
        "service_states": [
            "CANCELLED"
        ],
        "services": [
            "4dc0809f-ed91-4b68-b912-5bd6064d901e"
        ]
    },
    "rating": {
        "bill_in_advance": {
            "period": 3,
            "uot": "DAYS"
        },
        "prorate_period": {
            "enabled": true,
            "threshold_day": 15
        }
    },
    "invoicing": {
        "invoice_type_id": "",
        "credit_note_type_id": ""
    },
    "usage_billing": {
        "verify_allowance": "true"
    }
}

HTTP/1.1 200 OK 
Subscription Action Categories
GET /action_categories
GET /action_categories/{id}
POST /action_categories
PUT /action_categories/{id}
DELETE /action_categories/{id}
List Subscription Action Categories
GET /action_categories

Returns a list of subscription action categories

Request parameters

search_value
string optional

Search for action categories using their name

business_classification_code
string optional

The business classification code of the category

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The unique identifier of the action category

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
name
string

The action category name

Example:
Cancellation due to cost
description
string

The action category description

Example:
Service cancelled due to high monthly cost
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/action_categories HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "name": "Cancellation due to cost",
            "description": "Service cancelled due to high monthly cost"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Subscription Action Category
GET /action_categories/{id}

Returns a single subscription action category

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
name
string

The action category name

Example:
Cancellation due to cost
description
string

The action category description

Example:
Cancellation due to high monthly cost
actions
Array

List of subscription actions business classification codes

Min items: 1
Object
behaviour_code
string required

The action’s behaviour code

Enumeration:
CANCEL_SERVICE
CHANGE_SERVICE
Example:
CHANGE_SERVICE
business_classification_code
string required

The action’s business classification code

Enumeration:
CANCEL_SERVICE

Applicable when business code is set to Cancel Service

UPGRADE_SERVICE

Applicable when business code is set to Change Service

DOWNGRADE_SERVICE

Applicable when business code is set to Change Service

Example:
DOWNGRADE_SERVICE
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/action_categories/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Cancellation due to cost",
    "description": "Cancellation due to high monthly cost",
    "actions": [
        {
            "behaviour_code": "CHANGE_SERVICE",
            "business_classification_code": "DOWNGRADE_SERVICE"
        }
    ]
}
Create Subscription Action Category
POST /action_categories

Creates a new subscription action category

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The action category’s name

Example:
Cancellation due to cost
description
string

The action category’s description

Example:
Cancellation because of high monthly cost
actions
Array required

List of subscription actions business classification codes

Min items: 1
Unique items: YES
Object
behaviour_code
string required

The behaviour code fo the action

Enumeration:
CANCEL_SERVICE
CHANGE_SERVICE
Example:
CHANGE_SERVICE
business_classification_code
string required

The business classification code of the action

Enumeration:
CANCEL_SERVICE

Applicable when business code is set to Cancel Service

UPGRADE_SERVICE

Applicable when business code is set to Change Service

DOWNGRADE_SERVICE

Applicable when business code is set to Change Service

Example:
DOWNGRADE_SERVICE

Responses

200 OK
Body
Object
id
string

The unique identifier of the subscription action category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/action_categories HTTP/1.1 

Content-Type: application/json

{
    "name": "Cancellation due to cost",
    "description": "Cancellation because of high monthly cost",
    "actions": [
        {
            "behaviour_code": "CHANGE_SERVICE",
            "business_classification_code": "DOWNGRADE_SERVICE"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Subscription Action Category
PUT /action_categories/{id}

Updates an existing subscription action category

Path variables

id
string required

The unique identifier of the subscription action category

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The action category’s name

Example:
Cancellation due to cost
description
string

The action category’s description

Example:
Cancellation because of high monthly cost
actions
Array required
Min items: 1
Unique items: YES
Object
behaviour_code
string required

The behaviour code of the action

Enumeration:
CANCEL_SERVICE
CHANGE_SERVICE
Example:
CHANGE_SERVICE
business_classification_code
string required

The business classification code of the action

Enumeration:
CANCEL_SERVICE

Applicable when business code is se to Cancel Service

UPGRADE_SERVICE

Applicable when business code is set to Change Service

DOWNGRADE_SERVICE

Applicable when business code is set to Change Service

Responses

200 OK
Body
Object
id
string

The unique identifier of the subscription action category

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/action_categories/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "Cancellation due to cost",
    "description": "Cancellation because of high monthly cost",
    "actions": [
        {
            "behaviour_code": "CHANGE_SERVICE",
            "business_classification_code": "UPGRADE_SERVICE"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Subscription Action Category
DELETE /action_categories/{id}

Deletes a subscrpion action category

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

200 OK

The request has succeeded

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/action_categories/{id} HTTP/1.1 

HTTP/1.1 200 OK 
Event-based Charges

List of Web aPIs for creating and managing Event-based Charges

GET /event_based_charges
PUT /event_based_charges
Get Event-based Charges
GET /event_based_charges

Returns the list of event-based charges

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The unique identifier of the event-based conditional charge

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
apply_on
string

Defines when the charge will be applied if the conditions are met

Enumeration:
IMMEDIATELLY

The charge is immediatelly invoiced

NEXT_BILLING_CYCLE

The charge is included in the upcoming bill

Default:
IMMEDIATELLY
Example:
NEXT_BILLING_CYCLE
event
string

The event that will trigger this rule.

Enumeration:
INITIATION
ACTIVATION
DEACTIVATION
CANCELLATION
DOWNGRADE
SWITCH
Example:
CANCELLATION
expense
Object

The expense service that will be invoiced

id
string

The unique identifier of the expense

Example:
90c0809f-ed91-4b68-b912-5bd6064d901e
sku
string

The expense’s SKU

Example:
CANCEL01
name
string

The expenses name

Example:
Cancellation Fee
conditions
Array

A set of conditions that should be met in order for the expense to be applied.

Object
id
string

Unique identifer of the condition

Example:
10c0809f-ed91-4b68-b912-5bd6064d901e
in_contract
boolean

The service should be in contract period.

Default:
false
Example:
true
existing_service
Object

The service on which the subscription eent is performed on

item_type
string

Define whether the condition applies for a product, a product type or a family.

Enumeration:
PRODUCT
TYPE
FAMILY
Example:
TYPE
item_id
string

The unique identifier of the product, type or family

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
item_name
string

The name of the product, type or family

Example:
Add-ons
change_to_service
Object

The service to which a service changes to. Applicable only for Downgrade and Switch subscription events

item_type
string

Define whether the condition applies for a product, a product type or a family.

Enumeration:
PRODUCT
TYPE
FAMILY
Example:
PRODUCT
item_id
string

The unique identifier of the product, type or family

Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e
item_name
string

The name of the product, type or family

Example:
Gold
period_before_contract_ends
Object

The condtin is met if the subscription event occurs a period before the contract ends. Applicable only if the condition is applied while the sevice is still in contract

period
string

The period’s value

Example:
1
uot
string

The period’s unit of time

Enumeration:
DAYS
MONTHS
Example:
MONTHS
contract
Object

The service’s contract period, in terms of duration

duration
integer

The contract period’s duration

Example:
12
uot
string

The unit of time of the contract period

Enumeration:
DAYS
MONTHS
YEARS
Example:
MONTHS
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/event_based_charges HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [ 
        {
            "id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "apply_on": "NEXT_BILLING_CYCLE",
            "event": "CANCELLATION",
            "expense": {
                "id": "90c0809f-ed91-4b68-b912-5bd6064d901e",
                "sku": "CANCEL01",
                "name": "Cancellation Fee"
            },
            "conditions": [
                {
                    "id": "10c0809f-ed91-4b68-b912-5bd6064d901e",
                    "in_contract": true,
                    "existing_service": {
                        "item_type": "TYPE",
                        "item_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
                        "item_name": "Add-ons"
                    },
                    "change_to_service": {
                        "item_type": "PRODUCT",
                        "item_id": "3dc0809f-ed91-4b68-b912-5bd6064d901e",
                        "item_name": "Gold"
                    },
                    "period_before_contract_ends": {
                        "period": "1",
                        "uot": "MONTHS"
                    },
                    "contract": {
                        "duration": 12,
                        "uot": "MONTHS"
                    }
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Update Event-based Charges
PUT /event_based_charges

Updates the list of event-based charges

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
content
Array
Object
apply_on
string required

Defines when the charge will be applied if the conditions are met

Enumeration:
IMMEDIATELLY
ON_NEXT_BILLING_CYCLE
Default:
IMMEDIATELLY
Example:
ON_NEXT_BILLING_CYCLE
event
string required

The event that will trigger this rule.

Enumeration:
INITIATION
ACTIVATION
DEACTIVATION
CANCELLATION
DOWNGRADE
SWITCH
Example:
DOWNGRADE
expense_id
string required

The expense service that will be invoiced

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
conditions
Array

A set of conditions that should be met in order for the expense to be applied.

Object
in_contract
boolean

The service should be in contract period.

Default:
false
Example:
true
existing_service
Object

The service on which the subscription eent is performed on

item_type
string required

Define whether the condition applies for a product, a product type or a family.

Enumeration:
PRODUCT
TYPE
FAMILY
Example:
PRODUCT
item_id
string required

The unique identifie rof the product, product type or family.

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e
change_to_service
Object

The service to which a service changes to. Applicable only for Downgrade and Switch subscription events

item_type
string required

Define whether the condition applies for a product, a product type or a family.

Enumeration:
PRODUCT
TYPE
FAMILY
Example:
PRODUCT
item_id
string required

The unique identifie rof the product, product type or family.

Example:
2ac0809f-ed91-4b68-b912-5bd6064d901e
period_before_contract_ends
Object

The condtin is met if the subscription event occurs a period before the contract ends. Applicable only if the condition is applied while the sevice is still in contract

period
string

The period’s value

Example:
12
uot
string

The period’s unit of time

Enumeration:
DAYS
MONTHS
YEARS
Example:
MONTHS
contract
Object

The service’s contract period, in terms of duration.

duration
integer

The contract period’s duration

Example:
12
uot
string

The contract period’s unit of time

Enumeration:
DAYS
MONTHS
YEARS
Example:
MONTHS

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/event_based_charges HTTP/1.1 

Content-Type: application/json

{
    "content": [
        {
            "apply_on": "ON_NEXT_BILLING_CYCLE",
            "event": "DOWNGRADE",
            "expense_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
            "conditions": [
                {
                    "in_contract": true,
                    "existing_service": {
                        "item_type": "PRODUCT",
                        "item_id": "4dc0809f-ed91-4b68-b912-5bd6064d901e"
                    },
                    "change_to_service": {
                        "item_type": "PRODUCT",
                        "item_id": "2ac0809f-ed91-4b68-b912-5bd6064d901e"
                    },
                    "period_before_contract_ends": {
                        "period": "12",
                        "uot": "MONTHS"
                    },
                    "contract": {
                        "duration": 12,
                        "uot": "MONTHS"
                    }
                }
            ]
        }
    ]
}
Event-based Recurring Charges
GET /event_based_recurring_charges
PUT /event_based_recurring_charges
Get Event-based Recurring Charges
GET /event_based_recurring_charges

Returns a list of event-based, recurring charges

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string
event_to_apply
string
Example:
INITIATION
event_to_terminate
string
Example:
DISABLE_FROM_DEVICE
expense
Object
id
string
sku
string
name
string
conditions
Array
Object
in_contract
boolean
Example:
true
contract_period
Object
duration
integer
Example:
12
uot
string
Example:
DAYS
service
Object
item_type
string
Example:
PRODUCT
item_id
string
item_name
string
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/event_based_recurring_charges HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "event_to_apply": "INITIATION",
            "event_to_terminate": "DISABLE_FROM_DEVICE",
            "expense": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "conditions": [
                {
                    "in_contract": true,
                    "contract_period": {
                        "duration": 12,
                        "uot": "DAYS"
                    },
                    "service": {
                        "item_type": "PRODUCT",
                        "item_id": "",
                        "item_name": ""
                    }
                }
            ]
        }
    ]
}
Update Event-based Recurring Charges
PUT /event_based_recurring_charges

Updates the set of event-based recurring charges

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
content
Array
Object
id
string
event_to_apply
string
Example:
INITIATION
event_to_terminate
string
Example:
DISABLE_FROM_DEVICE
expense
Object
id
string
sku
string
name
string
conditions
Array
Object
in_contract
boolean
Example:
true
contract_period
Object
duration
integer
Example:
12
uot
string
Example:
DAYS
service
Object
item_type
string
Example:
PRODUCT
item_id
string
item_name
string

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/event_based_recurring_charges HTTP/1.1 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "event_to_apply": "INITIATION",
            "event_to_terminate": "DISABLE_FROM_DEVICE",
            "expense": {
                "id": "",
                "sku": "",
                "name": ""
            },
            "conditions": [
                {
                    "in_contract": true,
                    "contract_period": {
                        "duration": 12,
                        "uot": "DAYS"
                    },
                    "service": {
                        "item_type": "PRODUCT",
                        "item_id": "",
                        "item_name": ""
                    }
                }
            ]
        }
    ]
}

HTTP/1.1 200 OK 
Usage Charge Limits
POST /usage_charge_limits
GET /usage_charge_limits
PUT /usage_charge_limits/{id}
DELETE /usage_charge_limits/{id}
Create Usage Charge Limits
POST /usage_charge_limits

Create new rule for Usage Charge Limits

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required
usage_amount
number nullable
Example:
999.99
usage_records
integer nullable
Example:
10
products
Array
Min items: 1
Object
item_type
string
Example:
PRODUCT
item_id
string
Example:
5cc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The unique identfier of the new Usage Charge Limit Rule

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/usage_charge_limits HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "usage_amount": 999.99,
    "usage_records": 10,
    "products": [
        {
            "item_type": "PRODUCT",
            "item_id": "5cc0809f-ed91-4b68-b912-5bd6064d901e"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Get Usage Charge Limits
GET /usage_charge_limits

Returns the list of Usage Charge Limits. Rules on maximum allowed un-billed-usage. Either a usage amount or number of usage records is specified per rule.

Request parameters

sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

Unique identifier of the Usage Charge Limit rule

name
string
usage_amount
number

The maximum allowed un-billed usage amount. Defined in default currency

Example:
999.99
usage_records
integer

The maximum allownce number of un-billed usage records

Example:
10
currency
string

The currency of the un-billed usage amount

Example:
EUR
products
Array

List of products and/or product types on which usage charge limits will be applied, i.e. once the usage of the speified products is reached, then their usage is immediatelly billed.

Object
item_type
string

Define whether usage charge limit is applied per product or product type

Enumeration:
PRODUCT
TYPE
item_id
string

The unique identifier of the product or product type accordingly.

Example:
5cc0809f-ed91-4b68-b912-5bd6064d901e
item_name
string

The name of the product or the product type

Example:
TV Service
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/usage_charge_limits HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "",
            "name": "",
            "usage_amount": 999.99,
            "usage_records": 10,
            "currency": "EUR",
            "products": [
                {
                    "item_type": "PRODUCT",
                    "item_id": "5cc0809f-ed91-4b68-b912-5bd6064d901e",
                    "item_name": "TV Service"
                }
            ]
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Update Usage Charge Limits
PUT /usage_charge_limits/{id}

Returns the list of Usage Charge Limits. Rules on maximum allowed un-billed-usage. Either a usage amount or number of usage records is specified per rule.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string
usage_amount
number nullable
Example:
999.99
usage_records
integer nullable
Example:
10
products
Array
Min items: 1
Object
item_type
string
Example:
PRODUCT
item_id
string
Example:
5cc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

The unique identfier of the updated sage Charge Limit Rule

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/usage_charge_limits/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "",
    "usage_amount": 999.99,
    "usage_records": 10,
    "products": [
        {
            "item_type": "PRODUCT",
            "item_id": "5cc0809f-ed91-4b68-b912-5bd6064d901e"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Usage Charge Limits
DELETE /usage_charge_limits/{id}

Deletes a Usage Charge Limits rule.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

204 No Content
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/usage_charge_limits/{id} HTTP/1.1 

HTTP/1.1 204 No Content 
Taxes
POST /tax_rates/
PUT /tax_rates/{id}
DELETE /tax_rates/{id}
GET /tax_rates/
GET /tax_rates/{id}
Create Tax Rate
POST /tax_rates/

Creates a new Tax Rate. A single Tax Rate can be created per Web API call.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string required

The name of the tax rate

Example:
Standard VAT
description
string

The description of the tax rate

Example:
Standard VAT of 20%
rate_percentage
number required

Tax rate percentage

Example:
19
country_code
string required

The country at which the tax rate is applied

Example:
GR
tax_code
string required

The tax rate’s reated tax code

Enumeration:
VAT
SALES_TAX
TAX_EXEMPT
OTHER
Example:
VAT
as_of_date
integer epoch required

The date from which the tax rate is applied. If not specified, it defaults to the date on which the rate % is set.

Example:
1623225742
supply_method
string

The type of the event

Enumeration:
DELIVERY

Delivered to the customer’s address

PICK_UP

Picked up by the customer from a venue

DIRECT_SALES

Online sales of services

Example:
DELIVERY
is_default
boolean

Defines whether tax rate is the default one. Default tax raes are applied when invoicing process cannot identify a tax to be applied because of missing country of agreement of contact’s billing address. Defaults to False. Only one tax rate per tax code and per country can be specified.

Default:
false
Example:
true

Responses

200 OK
Body
Object
id
string

The unique identifier of the new Tax Rate

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
POST https://sandbox.crm.com/backoffice/v1/tax_rates/ HTTP/1.1 

Content-Type: application/json

{
    "name": "Standard VAT",
    "description": "Standard VAT of 20%",
    "rate_percentage": 19.00,
    "country_code": "GR",
    "tax_code": "VAT",
    "as_of_date": 1623225742,
    "supply_method": "PICK_UP",
    "is_default": "true"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Update Tax Rate
PUT /tax_rates/{id}

Updates an existing Tax Rate. A single Tax Rate can be updated per Web API call.

Path variables

id
string required

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
name
string

The name of the tax rate

Example:
Standard VAT
description
string

The description of the tax rate

Example:
Stadard VAT for 24%
rate_percentage
number

Tax rate percentage

Example:
19
as_of_date
integer epoch

The date from which the tax rate is applied. If not specified, it defaults to the date on which the rate % is set.

Example:
1623226230
country_code
string

The country at which the tax rate is applied

Example:
GR
tax_code
string

The tax rate’s related tax code

Enumeration:
VAT
SALES_TAX
TAX_EXEMPT
OTHER
Example:
VAT
supply_method
string

The supply method of the order through which the product will be purchased and provided to the customer

Enumeration:
ON_SITE
DELIVERY
PICK_UP
Example:
DELIVERY
is_default
boolean

Defines whether tax rate is the default one. Default tax raes are applied when invoicing process cannot identify a tax to be applied because of missing country of agreement of contact’s billing address. Defaults to False. Only one tax rate per tax code and per country can be specified.

Example:
true
product_conditions
Array

A set of products on which the tax rate will be applied

Object
id_type
string required

The product family’s unique identifier

Enumeration:
PRODUCT
FAMILY
Example:
PRODUCT
id
string required

The unique identifier of either a product pr product family depending on the id_type selection

Example:
3dc0809f-ed91-4b68-b912-5bd6064d901e
location_conditions
Array

Define additional location conditions in free text

Object
town_city
string

Town/City

state_province_county
string

State/Province/County

Responses

200 OK
Body
Object
id
string

The unique identifier of the updated Tax Rate

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/tax_rates/{id} HTTP/1.1 

Content-Type: application/json

{
    "name": "Standard VAT",
    "description": "Stadard VAT for 24%",
    "rate_percentage": 19,
    "as_of_date": 1623226230,
    "country_code": "GR",
    "tax_code": "VAT",
    "supply_method": "DELIVERY",
    "is_default": "true",
    "product_conditions": [
        {
            "id_type": "PRODUCT",
            "id": "3dc0809f-ed91-4b68-b912-5bd6064d901e"
        }
    ],
    "location_conditions": [
        {
            "town_city": "",
            "state_province_county": ""
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": ""
}
Delete Tax Rate
DELETE /tax_rates/{id}

Deletes an existing Tax Rate. A single Tax Rate can be deleted per Web API call. A tax rate can be deleted only if it was never applied in an Invoice or Credit Note

Path variables

id
string required

The Tax rate identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
DELETE https://sandbox.crm.com/backoffice/v1/tax_rates/{id} HTTP/1.1 

HTTP/1.1 200 OK 
List Tax Rates
GET /tax_rates/

Returns a list of all configured Tax Rates

Request parameters

coutry_code
string optional

Filters Tax Rates per country

Example:
GRE
sort
string optional

Defines on which attribute the results should be sorted

Default:
CREATED_DATE
Examples:
CREATED_DATEUPDATED_DATENAMESCHEDULED_DATE
order
string optional

Defines how the results will be ordered

Default:
DESC
page
integer optional

The page number that should be retrieved

Default:
1
size
integer optional

The size (total records) of each page

Default:
10
search_value
string optional

Search for Tax rates based on their Name or Description

product_id
string optional

The idnetifier of the product on which the tax rate is applied

product_family_id
string optional

The idnetifier of the product family on which the tax rate is applied

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
content
Array
Object
id
string

The unique identifer of the tax rate

Example:
3FD9C84FA60F9FE407140E20F707726A
name
string

Tax rate name

Example:
Standard VAT
description
string

Tax rate description

Example:
Cyprus Standard VAT
rate_percentage
number

Tax rate percentage

country_code
string

The country of agreement at which the Tax rate is applied

Example:
CYP
tax_code
string

The tax code

Enumeration:
VAT
TAX_EXEMPT
SALES_TAX
OTHER
Example:
VAT
is_default
boolean

Defines whethe rthe Tax rate is the defualt one for the specified country

Example:
true
paging
Object
page
integer

The page number

Example:
2
size
integer

The number of records per page

Example:
20
total
integer

The overal number of records

Example:
5124
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/tax_rates/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "3FD9C84FA60F9FE407140E20F707726A",
            "name": "Standard VAT",
            "description": "Cyprus Standard VAT",
            "rate_percentage": 1,
            "country_code": "CYP",
            "tax_code": "VAT",
            "is_default": "true"
        }
    ],
    "paging": {
        "page": 2,
        "size": 20,
        "total": 5124
    }
}
Get Tax Rate
GET /tax_rates/{id}

Returns detailed information of a Tax Rate. A single Tax Rate is returned in each Web API call.

Path variables

id
string required

The Tax rate’s identifier

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 OK
Body
Object
id
string

Tax Rate unique identifier

Example:
3FD9C84FA60F9FE407140E20F707726A
name
string

Tax Rate name

Example:
Standard VAT
description
string

Tax Rate description

Example:
Standard VAt for Cyprus
rate_percentage
number

Tax Rate percentage

Example:
19
as_of_date
integer epoch

The date from which the tax rate is applied.

Example:
1623227590
country_code
string

The country of agreement at which the Tax Rate will be applied

Example:
CYP
tax_code
string

The tax code

Enumeration:
VAT
SALES_TAX
TAX_EXEMPT
OTHER
supply_method
string

The supply method of the order thrugh which the product will be provided to the cusotmer.

Enumeration:
ON_SITE
DELIVERY
PICK_UP
Example:
DELIVERY
is_default
boolean

Defines whether tax rate is the default one. Default tax raes are applied when invoicing process cannot identify a tax to be applied because of missing country of agreement of contact’s billing address. Defaults to False. Only one tax rate per tax code and per country can be specified.

Example:
true
product_conditions
Array

List of products or product families at which the tax rate will be applied

Object
id_type
string

Define either a product or a product family

Enumeration:
PRODUCT
FAMILY
Example:
PRODUCT
id
string

The identfier of the product or the product family

location_conditions
Array

List of location conitions at which the tax rate will be applied. this lis tof conditions are appleid additionally compared to the rate’s Country condition. Conditions are specified in free text

Object
town_city
string

Town.City

state_province_county
string

State/Privince/County

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/tax_rates/{id} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "3FD9C84FA60F9FE407140E20F707726A",
    "name": "Standard VAT",
    "description": "Standard VAt for Cyprus",
    "rate_percentage": 19.00,
    "as_of_date": 1623227590,
    "country_code": "CYP",
    "tax_code": "SALES_TAX",
    "supply_method": "DELIVERY",
    "is_default": "true",
    "product_conditions": [
        {
            "id_type": "PRODUCT",
            "id": ""
        }
    ],
    "location_conditions": [
        {
            "town_city": "",
            "state_province_county": ""
        }
    ]
}
Wallets
GET /wallet_settings
PUT /wallet_settings
Get Wallet Settings
GET /wallet_settings

Retrieves the configured Wallet Settings that include Limits and Fees applied on performing various walet-related transactions such as Top-ups and Transfers.

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Responses

200 200

Successful Request

Body
Object
enable_auto_topup
boolean

Determines whether the CRM Wallet will be automatically topped-up when used as a pament method. If enabled, the wallet is topped up using the contact’s primary account, if any

Default:
false
Example:
true
limit_rules
Array

Defines the limit rules applied on specific wallet.

Object
name
string required

The name of the rule

Example:
Monthly Limits for VIP
maximum_amount
number required nullable

The maximum allowed amount among all wallet-related transactions. The amount is always set to the business’s base currency

Example:
9.99
maximum_number
integer required nullable

The maximum number of wallet-related transactions allowed

Example:
10
period
string required

Limits are applied on transactions performed within the specified period of time. In all cases, the period is defined based on calendar. e.g. Montlhy refers to a calendar month

Enumeration:
DAILY
MONTHLY
ANNUAL
Default:
MONTHLY
Example:
DAILY
transaction_type
Array

The wallet transaction type for which the limit is applied

string
Enumeration:
DEBIT
CREDIT
TOPUP
TRANSFER
Example:
TOPUP
conditions
Array

The conditions that should be met to apply the limit

Object
entity
string
Enumeration:
ACCOUNT_CLASSIFICATION
CONTACT_CATEGORY
Example:
ACCOUNT_CLASSIFICATION
id
string

The entity’s unique identifier

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the entity

Example:
VIP
fees_rules
Array

Defines the global fees to be applied over a period or on transactions executed against wallets

Object
name
string required

The name of the rule

Example:
VIP
value_type
string

The value type of the fee

Enumeration:
AMOUNT
PERCENTGE
value
number

The value of the fee

Example:
0.01
applied_on
string

The event to apply the fee

Enumeration:
TRANSACTION
PERIOD
Default:
TRANSACTION
Example:
TRANSACTION
period
integer

The period when the fees will be applied

Example:
1
period_uot
string

The UOT of the period

Enumeration:
DAY
MONTH
YEAR
applied_transaction
Array

The transactions that the fee will be applied on

string
Enumeration:
DEBIT
CREDIT
TOPUP
TRANSFER
Example:
TOPUP
conditions
Array
Object
entity
string
Enumeration:
ACCOUNT_CLASSIFICATION
CONTACT_CATEGORY
Example:
ACCOUNT_CLASSIFICATION
id
string

The unique identifier of the entity

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the entity

Example:
Enhanced
400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
GET https://sandbox.crm.com/backoffice/v1/wallet_settings HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "enable_auto_topup": "true",
    "limit_rules": [
        {
            "name": "Monthly Limits for VIP",
            "maximum_amount": 9.99,
            "maximum_number": 10,
            "period": "DAILY",
            "transaction_type": [
                "TOPUP"
            ],
            "conditions": [
                {
                    "entity": "ACCOUNT_CLASSIFICATION",
                    "id": "4AD9C84FA60F9FE407140E20F707726A",
                    "name": "VIP"
                }
            ]
        }
    ],
    "fees_rules": [
        {
            "name": "VIP",
            "value_type": "PERCENTGE",
            "value": 0.01,
            "applied_on": "TRANSACTION",
            "period": 1,
            "period_uot": "YEAR",
            "applied_transaction": [
                "TOPUP"
            ],
            "conditions": [
                {
                    "entity": "ACCOUNT_CLASSIFICATION",
                    "id": "4AD9C84FA60F9FE407140E20F707726A",
                    "name": "Enhanced"
                }
            ]
        }
    ]
}
Update Wallet Settings
PUT /wallet_settings

Update the wallet settings

Request headers

authorization
string optional

Authorization Token

Example:
eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
api_key
string optional

The secret api key required for API calls to ensure that the client is trusted

Example:
4dc0809f-ed91-4b68-b912-5bd6064d901e

Request body

Object
enable_auto_topup
string

Determines whether the CRM Wallet will be automatically topped-up when used as a pament method. If enabled, the wallet is topped up using the contact’s primary account, if any

Default:
false
Example:
true
limit_rules
Array

Defines the limit rules applied on specific wallet. Applied on all wallets unless overriden

Object
name
string

The name of the rule

Example:
VIP
maximum_amount
number

The maximum amount allowed

Example:
100
maximum_number
integer

The maximum number of transactions allowed

period
string

The period for which the limit is applied

Enumeration:
DAILY
MONTHLY
ANNUAL
transaction_type
Array

The wallet transaction type for which the limit is applied

string
Enumeration:
DEBIT
CREDIT
TOPUP
TRANSFER
Example:
TOPUP
conditions
Array
Object
entity
string
Enumeration:
ACCOUNT_CLASSIFICATION
CONTACT_CATEGORY
Example:
ACCOUNT_CLASSIFICATION
id
string

The unique identifier of the entity

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the entity

Example:
Enhanced
fees_rules
Array

Defines the global fees to be applied over a period or on transactions executed against wallets

Object
name
string

The name of the rule

Example:
VIP
value
number

The value of the fee

Example:
0.1
value_type
string

The value type of the fee

Enumeration:
AMOUNT
PERCENTAGE
applied_on
string

The event to apply the fee

Enumeration:
TRANSACTION
PERIOD
period
integer

The period when the fees will be applied

Example:
1
period_uot
string

The UOT of the period

Enumeration:
DAY
MONTH
YEAR
applied_transaction
Array

The transactions that the fee will be applied on

string
Enumeration:
DEBIT
CREDIT
TOPUP
TRANSFER
Example:
TOPUP
conditions
Array
Object
entity
string
Enumeration:
ACCOUNT_CLASSIFICATION
CONTACT_CATEGORY
Example:
ACCOUNT_CLASSIFICATION
id
string

The unique identifier of the entity

Example:
4AD9C84FA60F9FE407140E20F707726A
name
string

The name of the entity

Example:
Enhanced

Responses

200 200

Successful Request

400 Bad Request

The input request was invalid or incorrect, often due to missing a required parameter

401 Unauthorized

The provided API Key or Token is invalid

403 Forbidden

The API key or Token does not have permissions to perform the request

404 Not Found

The requested resource does not exist

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request

502 Bad Gateway

The server received an invalid response from the upstream server it accessed in attempting to fulfill the request

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance

504 Gateway Timeout

The server did not receive a timely response from the upstream server

Example 1
PUT https://sandbox.crm.com/backoffice/v1/wallet_settings HTTP/1.1 

Content-Type: application/json

{
    "enable_auto_topup": "true",
    "limit_rules": [
        {
            "name": "VIP",
            "maximum_amount": 100,
            "maximum_number": 1,
            "period": "MONTHLY",
            "transaction_type": [
                "TOPUP"
            ],
            "conditions": [
                {
                    "entity": "ACCOUNT_CLASSIFICATION",
                    "id": "4AD9C84FA60F9FE407140E20F707726A",
                    "name": "Enhanced"
                }
            ]
        }
    ],
    "fees_rules": [
        {
            "name": "VIP",
            "value": 0.1,
            "value_type": "PERCENTAGE",
            "applied_on": "PERIOD",
            "period": 1,
            "period_uot": "MONTH",
            "applied_transaction": [
                "TOPUP"
            ],
            "conditions": [
                {
                    "entity": "ACCOUNT_CLASSIFICATION",
                    "id": "4AD9C84FA60F9FE407140E20F707726A",
                    "name": "Enhanced"
                }
            ]
        }
    ]
}