Contacts Onboarding Guide

1 Self-Service API
- 1.1 Step 1 - Register a new customer
- 1.2 Step 2
- 1.3 Step 3
- 1.4 Step 4 – Request an OTP token if user logged out
- 1.5 Step 5 – Using a Refresh Token
2 Back-Office API
- 2.1 Step 1 - Add Contact
- 2.2 Step 2 – Add Authentication credentials

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.

POST /contacts/register HTTP/1.1 

api_key: ab5f8b2e-092f-4848-8f46-31df1c014060
Content-Type: application/json

{
    "first_name": "Ahmed",
    "last_name": "Samir",
    "identity": {
        "provider": "PHONE",
        "phone_number": "9947823",
        "country_code": "CYP"
    },
    "service_acceptance": "true",
    "email_opt_out": "true",
    "sms_opt_out": "true"
}

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.

curl --location --request POST 'https://app.crm.com/self-service/v1/contacts/validate-otp' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'api_key: af42c488-b040-4991-b300-97378626fd63' \
--data-raw '{
    "credentials": [
        {
            "name": "EMAIL",
            "value": "andystewarduk+me1@gmail.com"
        }
    ],
    "code": "812279"
}'

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.

{
    "contact": {
        "title": null,
        "avatar": null,
        "first_name": "Andy",
        "last_name": "Steward",
        "is_verified": null
    },
    "organisations": [
        {
            "name": "DropHop",
            "id": "943148fd-a8b7-4634-b39b-5120221967d3",
            "org_type": "BUSINESS"
        }
    ],
    "access_token": "access_token ",
    "refresh_token": "refresh_token",
    "exp": 1629364506000
}

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

CRM.COM Resources