Plugin Integrators

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

Welcome to the CRM.COM Application Programming Interface (API) documentation for Provisioning Provider Integrations

Release Date April 21, 2021

This is the first release of the CRM V5 Provisioning Provider APIs

CRM.COM BackOffice API uses either API keys to authenticate requests or an authentication JWT token obtained from a user successful logging in

API keys can be accessed and managed in the CRM.COM Dashboard. Such API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth

All API requests must be made over HTTPS. API requests made over plain HTTP or without authentication will fail. API keys authentication is made using -H “api_key : crm_test_;dwfwgiuhjr412edws”, while User Bearer Auth is achieved using -H “Authorization: Bearer JWT_TOKEN”

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

2xx success status codes confirm that your request worked as expected
4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
5xx error status codes are rare and indicate an error with Stripe’s servers

Please note that some 4xx errors that could be handled programmatically (e.g. a contact already exists) contain the following informaiion

HTTP Code (programmatic consumption)
Message (human-readable)
Attribute (attribute that caused the error)

Below is a list of our common error codes that can be returned, along with additional information about how to resolve them

Manage Entitlements

POST /provisioning/entitlements

Send Message

POST /provisioning/message

Get IRD Commands

GET /provisoning/ird_commands

Send IRD Command

POST /provisioning/ird_command

POST /provisioning/entitlements

Send to the adepter whenever there’s a change in the set of subscirption services (e.g. whenever an authorisation or a de-authorisation signal must be sent)

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

subscription

Object

The subscription that groups together the services

id

string

The unique identifier of the subsription

code

string

The subscription’s code

first_activation

integer

The date on which the subscription was first activated

Example:

1618998627

services_to_authorise

Array

Object

external_reference

string

Example:

Premium

state_date

integer

Example:

123456788

end_date

integer

Example:

123456788

last_authorisation_date

integer

devices

Array

Object

external_reference

string

service_to_deauthorise

Array

Object

external_reference

string

Example:

Premium

devices

Array of string

Responses

200 200

The request has succeeded

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

POST https://sandbox.crm.com/backoffice/v1/provisioning/entitlements HTTP/1.1 

Content-Type: application/json

{
    "existing_services": [
        {
            "caid": "Premium",
            "authorisation_state": "AUTHORISED",
            "autohrisation_date": 123456788,
            "devices": [
                "" 
            ],
            "metadata_attributes": [
                {
                    "key": "",
                    "value": ""
                }
            ]
        }
    ],
    "new_services": [
        {
            "caid": "Premium",
            "state_date": 123456788,
            "end_date": 123456788,
            "devices": [
                ""
            ]
        },
                {
            "caid": "FIlms",
            "state_date": 123456788,
            "end_date": 123456788,
            "devices": [
                ""
            ]
        } 
    ],
    "removed_services": [
        {
            "caid": "Premium",
            "devices": [
                ""
            ]
        }
    ],
    "subscription_metadata": [
        {
            "key": "",
            "value": ""
        }
    ]
}

HTTP/1.1 200 OK

POST /provisioning/message

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

devices

Array required

The devices (serial numbers) that provisioning message will be sent to

Example:

[
    "SN1234","SN09123"
]

string

Example:

SN1234

message

string required

The message (from the communication plan) that will be sent

Example:

Free Trial Period Expires Soon. Join our awesome scheme!

type

string required

Defines on which communication channel the message will be sent

Enumeration:

OSD

Message will be shown On Screen Display (OSD)

MAIL

Message will be send via email

Responses

200 200

The request has succeeded

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

POST https://sandbox.crm.com/backoffice/v1/provisioning/message HTTP/1.1 

Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV

{
    "devices": [
        "SN1234"
    ],
    "message": "Free Trial Period Expires Soon",
    "type": "MAIL"
}

HTTP/1.1 200 OK

GET /provisoning/ird_commands

Retireve a list of IRD commands implemetned in the adapter To be moved under configuration

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

Responses

200 OK

Body

Object

content

Array

Object

code

string

Example:

RESET_PIN

name

string

Example:

Reset PIN

label

string

description

string

Example:

Resets the PIN to a given value

metadata_attributes

Array

Object

key

string

Example:

label

string

Example:

description

string

Example:

the new pin

field

string

Example:

TEXTBOX

is_mandatory

boolean

Example:

true

POST /provisioning/ird_command

Any IRD command

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

external_reference

string

ird_code

string

Example:

RESET_PIN, RESET_DEVICE, ENFORCE_DOWNLOAD

device_location

string

metadata_attributes

Array

Object

key

string

Example:

value

string

Example:

1234

Responses

200 200

The request has succeeded

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

POST https://sandbox.crm.com/backoffice/v1/provisioning/services HTTP/1.1 

Content-Type: application/json

{
    "services": [
        {
            "caid": "123",
            "start_date": 12345678,
            "end_date": 12345645,
            "devices": [
                "abc123"
            ]
        }
    ]
}

HTTP/1.1 200 OK

Set Provider Attributes

PUT /provisioning/settings

Get Provider Attributes

GET /provisioning/settings

Generate Provider Key

POST /provisioning/apikeys

PUT /provisioning/settings

Send the required provider attributes (as defined in the provisioning provider adapter) as specified within CRM

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

parameters

Array required

A set of parameters required for successfully integrating with the 3rd party provider

Object

key

string required

The parameter key

Example:

hostname

value

string required

The parameter value

Example:

crm.com/provider

Responses

200 200

The request has succeeded

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

PUT https://sandbox.crm.com/backoffice/v1/provisioning_providers HTTP/1.1 

Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e

{
    "parameters": [
        {
            "key": "hostname",
            "value": "crm.com/provider"
        }
    ]
}

HTTP/1.1 200 OK

GET /provisioning/settings

Retrieve the required attributes (as defined in the provisioning provider adapter) that need to be set within CRM, when setting up the provider. Part of the reponse, the provider media (image) is returned as well (if any)

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

Responses

200 OK

Body

Object

media_url

string

The provisioning provider media URL

Example:

crm.com/provider.png

parameters

Array

A set of parameters required for successfully integrating with the 3rd party provider

Object

key

string

The parameter key

Example:

hostname

value

string

The parameter value

Example:

crm.com/provider

label

string

The parameter label, used for display purposes

Example:

Hostname

type

string

The parameter type

Enumeration:

INTEGER

STRING

NUMBER

BOOLEAN

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

GET https://sandbox.crm.com/backoffice/v1/provisioning_providers HTTP/1.1 

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "media_url": "crm.com/provider.png",
    "parameters": [
        {
            "key": "hostname",
            "value": "crm.com/provider",
            "label": "Hostname",
            "type": "STRING"
        }
    ]
}

POST /provisioning/apikeys

Send the required provider attributes (as defined in the provisioning provider adapter) as specified within CRM

Request body

Object

organisation_id

string GUID required

The organisation (ext identifier) on which the provider will be associated with

Example:

ccc740f9-7482-b689-54ee-bd78e065d550

organisation_name

string required

The organisation (name) on which the provider will be associated with

Example:

crm

Responses

200 OK

Body

Object

key

string

The non-encrypted api key value that will be used for subsuquent provisioning authentication

Example:

key-123456789

400 400

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

401 401

The provided API Key or Token is invalid

403 403

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

404 404

The requested resource does not exist

500 500

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

502 502

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

503 503

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

504 504

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

Example 1

POST https://sandbox.crm.com/backoffice/v1/provisioning/apikeys HTTP/1.1 

Content-Type: application/json

{
    "organisation_id": "ccc740f9-7482-b689-54ee-bd78e065d550",
    "organisation_name": "crm"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "key": "key-123456789"
}