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:
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.)
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
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
The HTTP Status Codes used by the RESTful Wallet API.
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
PATCH - Update existing 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.