Getting Started

This documentation is for developers who want to use the Digital Engagement APIs to send and get information about their messages, subscribers, owners. It is essential that you’re familiar with web programming concepts and web data formats. The Digital Engagement APIs are HTTP-based RESTful APIs that use JSON Web Tokens for authorization. API request and response bodies are formatted in JSON.

API Platform uses these model classes to expose and document a web API having a bunch of built-in features:

  • Creating, retrieving, updating and deleting (CRUD) resources.

  • Data validation

  • Pagination

  • Filtering

  • Authentication (Basic HTTP)

  • Nice UI and machine- readable documentations (Swagger UI / OpenAPI)

Before you get started you need to ensure that you have completed the following steps:

  1. Get user credentials: You must contact your account manager or support team to obtain user credentials. Once the email is sent, the support team will send you the access credentials (username : your email address and password.)

  2. Get your API Key your account manager will provide the API Key

    Note

    API Keys provided by account managers do not have an expiration data

  3. Install cURL Make sure you have curl installed on your machine to make request to the APIs

    Make sure you have curl installed on your machine

    Note

    On Windows, use a Bash shell to make cURL calls

Status Codes

Code

Description

200 OK

Successful request

201 Created

New object saved

204 No content

Object deleted

400 Bad Request

Returns JSON with error message

401 Unauthorized

Couldn't authenticate your request

402 2FA Token required

Re-try request with user’s 2FA token as CB-2FA-Token header

403 Invalid scope

User hasn't authorized necessary scope

404 Not Found

No such object

429 Too Many requests

Your connection is being rate limited

500 Internal Server Error

Something went wrong

503 Service Unavailable

Your connection is being throttled or the service is down for maintenance

Making Requests

As per RESTful design patterns, Digital Engagement API implements HTTP verbs:

  • GET - Read resources

  • POST - Create new resources

  • PUT - Modify existing resources

  • DELETE - Remove resources

When making requests, arguments can be passed as params, form data or JSON with the correct Content-Type header.

Note

When accessing any of the endpoints, it is required to select the "Authorize" button to access the endpoint that is required to be used. When you want to use a selected endpoint, you need to select the “Try it out” button to have access to test the endpoint. Each endpoint requires authentication.

Authentication

The process of how a person authenticates in Authentication & Connect API  is associated with a token (API Key) that is encrypted and contains information intrinsic to the user, that is, a user who has a token is considered like a valid user or request. Even those tokens are validated in any of the APIs, for this reason, Authentication & Connect is the main API of the platform, because once you login to the system it provides you a valid token, which you  can use to access the other APIs, but the token has a expiration date so you can create a new API Key with a new configured expiration date.

To start using our API, you will need to add The authorization key in the header of all API requests. Using the authorization property with Bearer Schema.

Note

The Authorization Key will be provided by our support engineers when the integration process begins.

Base Response

{  
    "meta": {    
    "timestamp": 1597166699457,    
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",    
    "explain": "a descriptive text"  
},  
    "pagination": {
    "offset": "5f466c67e047e3293115e2ec",
    "limit": 10,
    "next": "5f466c67e047e3293115e2ec",
    "page": 5,
    "pages": 40,
    "total": 1000  
},
    "errors": {
    "reason": "failure reason",
    "details": [ {} ]
     },   "data": {},
    "items": [ {} ]
} 
Meta

The “meta” segment is dedicated to metadata regarding the call itself

timestamp

Call’s time mark

transactionId

Call’s transaction ID, this will help our teams to locate issues faster if arose

explain

Could be anything, is just a useful message regarding the operation or the call

Pagination

This is an optional segment that we will use with search endpoints or any other that needs to paginate its results

offset

How many items we are skipping in this call, this establish the initial point

limit

How many items per page we want to fetch in this call

next

Which is the next item to be queried to keep continuity when passing pages. This is meant to be used with offset

page

The current page indicator, this is useful for clients and help preventing them to

pages

Total pages, this value its relative and will depends on the total items in the collection and the limit used on the call

total

Total elements in the collection at the time of the invocation

Errors

The main error indicator always is the HTTP status code, however, this is a flexible placeholder if an endpoint wants to give more insights about the reasons of a failure.

The error segment is a free hand map that could contain any key and value combination.

reason

The failure main reason as a descriptive text

details

A key -> value map to add additional information about the error

Data

It will hold the Resource information, this field will come in the request that return a single element

Items

It will hold an Array of Resources, this field will come in the request that return a multiples elements

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.