Reference Guides

Getting Started

Welcome to the CRM.COM Reference Guides

The CRM.COM API is designed around REST, allowing you to manage subscription and/or rewards commerce in a simple, programmatic way using intuitive URL endpoints, conventional HTTP requests, response codes, authentication and verbs. The APIs are split into a number for KEY gateways to allow for different use cases:

Backoffice APIs – designed to allow primarily server to server communication where an integrator would like to build additional functionality to the existing CRM product, such as a Merchant APP or Server to Server based functionality. These API’s generally support Server to Server authentication using Secret Keys. However, the API also allow Authentication using a user name and password for building management interfaces.
Self-Service APIs – designed for implementation of Contact facing experiences such as Mobile Apps or Web based portals. These API’s are designed to operate using a single contact (customer) and are authenticated on that basis.
POS and eCommerce System Integration APIs - a set of API’s that are focused on implementing Point of Sale functionality to enable the Rewards platform to operate end to end for transaction acquisition to award and spend.
Passes Integration APIs - a set of APIs required by third party systems to integrate with CRM.COM for the purpose of managing passes and posting purchases using a pass.
Plugin Providers Integration APIs - a set of APIs required by third party systems to integrate with CRM.COM for the purpose of managing provisioning provider integrations and payment gateway provider integrations.

API Keys for calling services

Self-Service API Keys

CRM uses API keys to identify the tenant within the CRM cloud platform. The Self-Service API’s generally use an authenticated token using either credentials such as email password or OTP validation. However, some API’s need to be used before the authentication token can be used, such as Register new contact.

In this case it is necessary to use a public API key and provide this in the request header.

API Keys are created and can be copied using the Backoffice settings screen, any number of API Keys can be created and each with different security scopes.

The API key is added to the HTTP header as parameter api_key.

curl --location --request POST 'https://sandbox.crm.com/self-service/v1/contacts/register' \
--header 'api_key: 69691e1e-1d90-4355-8b78-acd41ef577f4' \
--header 'Content-Type: application/json' \
--data-raw '{
  "first_name" : "Jimmy",
  "last_name" : "Connors",
  "identity" : {
    "provider" : "PHONE",
    "phone_number" : "07566224395",
    "country_code" : "GBR"
  },
  "service_acceptance" : "true",
  "email_opt_out" : "true",
  "sms_opt_out" : "true"
}'

Once an authentication flow has been completed then the api_key is not required as part of the headers, as the necessary security information is taken from the token. Any Self-Service API call will have scope limited to the contact relating to the AUTH.

Back-Office API Keys

The Back Office API supports two types of API keys for different levels of security.

Public API Keys – to allow integrations such as web forms to call API’s that do not need authenticated access such as Registration of a new organisation.
Secret API Keys – Should only be used for Server to Server API calls from a trusted source. The Secret keys are used for integrations such as sending purchase events or creating or getting contact details. Secret Keys should never be exposed to a front end Web or APP interface as they could be intercepted and used to expose data.

Generation of secret API Keys is different and more secure than a public key. For example you will only have a chance to cut and paste the key when it is created it is not possible to reveal the key once created.

Secret keys can be rolled allowing them to be replaced and refreshed. The current key can be expired at a certain date to allow both values to be active until the expiration date.

Live / Test Mode

At any one time a user can switch between live and test mode in the Backoffice. This allows the API keys to be set up to generate test data that can be viewed in test mode before impacting the Live system.

A user can switch form Live to Test mode once logged in and any actions performed such as creating / viewing API keys will be based on the setting.

Authenticating To obtain JWT auth tokens.

Both the Self-Service and the Back-Office APIs also work with JWT tokens obtained via the authentication API’s. Backoffice authentication is based on Email / Password but the Self Service supports external authentication and OTP ( one time password ) to obtain a JWT token for use in subsequent APIs.

Back-Office Authentication

Backoffice API’s allow the use of username ( email ) and a password to obtain a JWT token. The user can be authenticated and have access to Multiple organisations at different levels (by masquerading, explained below). On initial Authentication the response will include the relevant organisations information.

curl 'https://app.crm.com/backoffice/v1/users/authenticate' \
  --data-raw '{"username":" johndoe@crm.com ","password":"Qwerty12"}' \
  --compressed

In the case of a service owner the contents of the token will identify that the user identified as a Service Owner so additional steps will be needed to retrieve a list of organisations.

Masquerading / Switching

When a user authenticates, it may be they fulfill roles in multiple organisations in the Network such as Business of a Service owner or Merchants of the Business.

The authentication will set the current organisation for the user and this information is part of the response. However that user may want to act on data in another organisation then the user can switch or obtain a new token that means subsequent API calls and security reflects another Business or Merchant or other type of organisation in the network.

Switch Token to masquerade

The new organisation is specified in the API path and the current token will be used to ensure that the user has the necessary levels of security to swap.

curl 'https://app.crm.com/backoffice/v1/organisations/e4895442-7a98-4f4d-8954-9c4827a5b452/masquerade' \
  -X 'POST' \
  -H 'Authorization: Bearer.<jwt_token> \
  --compressed

The response is the same as the previous authentication request but will modify the token to enable subsequent API calls to locate the correct data and security information.

Contacts

Self-Service API

CRM.COM has a concept of Contacts that represent the customers of a business and can either be a person ( B2C ) or a business ( B2B ).

Contacts are the starting point of any flow for business either as a Rewards contact or a Commerce / Billing contact or using both features of CRM.

Contacts can either be Joined up from an external system using shared unique ID via the Backoffice API’s or be registered via a CRM flow using the Self-Service APIs.

When using the Self-Service APIs a Contact Identity used for authentication is currently stored in the CRM system and supports.

Email / Password
Email – OTP
Phone – OTP
Facebook - oAuth

In order to demonstrate the flow using the Self-Service APIs we can look at the flow of an Application and the API’s necessary to create a new contact in Mobile APP using the Self-Service API for Customer Registration.

Initially let’s look at the case where the Authentication Method will be mobile telephone number and an OTP to validate.

The Registration screen is required to capture details of the customer and the necessary data to authenticate the customer.

In the example the minimal amount of data collected of a user forename and surname, and the Identity information of the Phone Number.

Step 1 - Register a new customer

New customers can be registered by collecting a minimal amount of customer data including Title, Forename, Surname and a way of providing credentials for future authentication. Optionally the contact can use OTP via email or Phone for future authentication. If using OTP make sure you have configured an SMS or Email provider in the Platform → Integrations menu.

Step 2

If the Registration required an OTP to be sent then the system will send a unique code via either email or SMS system. This code is then validated, and if validated then an Authenticated JWT token will be return for further API actions.

Step 3

If the OTP is validated, then the response of the API provides

Contact Details – details for presentation of the user including an avatar if set.
Organisations – This is a list of the organisations that the contact is joined to or shared with within the business network.
Authentication tokens.

The authentication tokens are JWT token that can be used for subsequent API calls that require authentication.

Step 4 – Request an OTP token if user logged out

In order to be able to sign in again then it is possible to request an OTP and follow the same flow as on the previous step.

The OTP will be sent via the Selected communication PHONE (SMS) or EMAIL and the OTP validation api used in the same way as on the registration request.

Step 5 – Using a Refresh Token

The refresh token allows the APP or portal to renew the token to allow the User to remained logged in if that behavior is required.

The approach is for an API call to be made or to locally store the expiry time of the token. Calling any API with an expired token will provide the relevant error message and the APP can silently refresh the token or respond as required.

The refresh token api provides a new token and a similar response to the other authentication API’s to ensure the most up to date data is available.

Back-Office API

Contacts in the Backoffice API do not use a registration flow to capture the details and or provide Identity for authentication. Creating a contact can be used to store and manage the contact details but cannot be used to store / change authentication credentials.

Step 1 - Add Contact

Contact can be created from server-based flows or agent based flows. The CRM entities allow an external system to provide either the unique ID ( max 36 typically a guid ) or if not one will be generated and cross reference code can be used to link.

https://speca.io/CRM/backoffice-admin#create-contact

Step 2 – Add Authentication credentials

For example, in a scenario where a new user is captured and created via a server to server request or some agent based flow and the user subsequently wants to access Portals or APP’s, and access to an APP or Portal is needed.

To add credentials there will need to be a Self-Service API flow that uses some identification details and accepts the new credentials. If a match to the key data is found the credentials will be added and the user can subsequently authenticate.

https://speca.io/CRM/self-service/_edit/m/add-authorisation-credentials-to-existing-contact