Getting Started

REST API allows you to programmatically transfer information over the internet using a predefined schema. WebEngage offers endpoints with specific requirements that perform actions and return data.

With the WebEngage APIs you can:

And much more!

Let's walk you through the basics:

User Authentication

🚧

Important!

REST API calls can be authenticated by using the key of only those Admins who have Account Management and Update Data permissions. Please check with the account owner if your API requests return the error, Unauthorized.

  • WebEngage follows Bearer Authentication Scheme for API access.

  • A unique REST API key is automatically created for each WebEngage Account Admin. Your key acts as the authorization bearer token and must be passed in the header of each API call. The token is valid for the entire lifetime of an Account Admin.

  • In case your API key is accidentally compromised or shared with a third-party, a new key can be requested from your Customer Success Manager or by dropping us an email at [email protected].

Getting Your Credentials

As shown below, navigate to Integrations > REST API in your dashboard to access your unique REST API Key and WebEngage Account License Code.

Click to enlarge

  • License Code: Replace the placeholder, YOUR_WEBENGAGE_LICENSE_CODE in all API calls to build the API endpoint URL for your account. Adding the incorrect code will cause the API call to fail (indicated by error code 404 in response).

  • API Key: Add it to the Authorization: Bearer <YOUR_API_KEY> header (by replacing the placeholder) in all API calls to authenticate the request. Adding the incorrect key or not adding one will cause the call to fail (indicated by error code 401 in response).

Example

In the below code snippet, we're calling the /user API to update the unique User ID, First Name, and Last Name for a user in WebEngage from an external source.

curl -X POST <HOST>/v1/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/users \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
    "userId": "johndoe21#",
    "firstName": "John",
    "lastName": "Doe"
    }'

Thus, we will:

  • Replace <HOST> with the applicable host mentioned here to build the resource endpoint URL.

  • Replace <YOUR_WEBENGAGE_LICENSE_CODE> with the respective account's license code to build the API resource endpoint.

  • ReplaceYOUR_API_KEY with our unique API key to authenticate the API call.

This is what the actual POST API call will look like:

curl -X POST https://api.webengage.com/v1/accounts/va1w264d/users \
    --header 'Authorization: Bearer <f414139-3cb9-4ed2-8od3-b8bbae8e7f8xY>' \
    --header 'Content-Type: application/json' \
    --data '{
    "userId": "johndoe21#",
    "firstName": "John",
    "lastName": "Doe"
    }'

Revoking API KEY

WebEngage Admins with Account Management access can choose to revoke API Key permissions of a specific admin. This can be done by:

  • Deleting the user
  • Revoking their Account Management and Update Data access permissions.

Click to enlarge

As shown above:

Step 1: Navigate to Profile > Account Admins in your dashboard.

Step 2: Click the Edit icon placed on the bottom right of the concerned admin's card.

Step 3: De-select Account Management and Update Data permissions.

Step 4: Click Save.

👍

Highly Recommended!

If the respective admin's API Key is being used in active API requests, then we highly recommend that you change the authorization bearer token for all API calls and use your API KEY to authenticate the calls.

Failing to do so will cause API call failure (unauthorized error). This could potentially disrupt transactional campaign delivery, message personalization, real-time data sync with WebEngage, and much more (depending on your usage of WebEngage APIs).

API Endpoint <HOST>

All available resources (/users, /events, /transaction, /feedback/, /survey/response/) can be accessed over HTTPS via the respective URLs listed below. The host URL serves as the parent link of the actual API resource endpoint and differs, depending on the WebEngage data center you're using for your account.

🚧

Please Note

WebEngage API Endpoint differs for updating Business Events, CSV data uploads, and making API calls through Journeys. Please refer to the respective docs for more details.

Global Data Center

If your WebEngage dashboard URL starts with dashboard.webengage.com, then it means you're using our Global Data Center. Please use the following host to access resources via API:

https://api.webengage.com/

India Data Center

If your WebEngage dashboard URL starts with dashboard.in.webengage.com, then it means you're using our India Data Center. Please use the following host to access resources via API:

https://api.in.webengage.com/

API Call Rate-Limit

With effect from September 25, 2020, we've introduced rate-limiting for our REST API resource endpoints to ensure predictable system uptime for you. The following API Call limits are applicable for all accounts:

API Call Type

Rate Limit

User Data Update

5K/minute

Event Data Update

5K/minute

Bulk User Data Update

1K/minute

Bulk Event Data Update

1K/minute

Creating Business Events

10/minute

Transactional Campaign API Request

100/minute

CSV Upload API Request

2/minute

Response

The data can be sent in either JSON or XML format. To select this, the format parameter can be passed in the URL as json or xml. Data is sent in JSON format by default. Any parameters can be passed as HTTP query string parameters in the API URLs.

Date

All timestamps are returned in yyyy-MM-ddTHH:mm:ssZ format.

👍

Example: 2013-01-26T07:31+0000

Response Container

{
    "response" : {
        "data" : {
            ...
        },
        "message" : "success",
        "status" : "success"
    }
}

Each API response is wrapped in the main response container. It contains the following properties:

  • status - Value can be success or error, depending on the server response.

  • message - Explains the reason for the corresponding status.

  • data - Contains the data for the requested resource.

Error Status Codes

Errors are returned using standard HTTP error code syntax. The response body is always in JSON.

Code

What It Means

How to Resolve

400

Invalid resource/parameters

Step 1: Please cross-check that you're using the correct License Code as a path parameter in the API resource endpoint.

Step 2: Please cross-check that you're accessing a valid WebEngage resource which can be either of the following: /users, /events, /transaction, /feedback/, /survey/response/

Step 2: Please drop in a few lines at [email protected] if the issue persists.

401

Invalid authentication/access | Unauthorized access

Step 1: Please reach out to [email protected], mentioning the API Key being used. We will help you identify the Account Admin to whom the API Key in question, belongs.

Step 2: Once Identified, go to Profile > Account Admins to cross-check if the respective admin has sufficient access permissions to Account Management and Update Data to authenticate REST API calls.

Step 3 (If the Account Admin doesn't have sufficient permissions): You can edit their access permissions by clicking Edit > Selecting Account Management and Update Data > Save.

Step 3 (If the Account Admin has been remove from your WebEngage dashboard): Please replace the invalid API Key in all active and future API calls with the Key of an admin that has sufficient permissions to authenticate the call.

404

Invalid URL

Step 1: Please cross-check if you're using the correct host (as per your WebEngage data center) as the parent URL for building the resource endpoint in your API call.

Step 2: Please drop in a few lines at [email protected] if the issue persists.

Please feel free to drop in a few lines at [email protected] in case you have further queries. We're always just an email away!

Updated a day ago



Getting Started


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.