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:

  • Track each user's preferences and their actions as User Attributes and Events, respectively.

  • Get survey data from WebEngage.

  • Pass data to WebEngage from third-party platforms like LeadSquare, Salesforce, or any other CRM/Lead Management system you're using.

  • Trigger highly personalized Transactional campaigns through Push, SMS, Web Push, and Email in your dashboard. (How it works)

  • Personalize a Journey campaign with real-time data from your servers OR update user details as per their journey experience. (How it works)

  • Send Business Events data to build Relays that enables you to automate product/platform communication. (How it works)

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 Data Paltform> Integrations > REST API in your dashboard to access your unique REST API Key and WebEngage Account License Code.

1425

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.

  • Replace<YOUR_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

Team members with roles Admin, Manager or any Custom Role with Update Data Management permission can choose to revoke API Key permissions of a specific team member. This can be done by:

  • Deleting the user
  • Changing their role. For more details on how to change the role of the team member or view the role permissions, kindly refer to Role-Based Access Control.

👍

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, /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/

Saudi Arabia Data Center

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

https://api.ksa.webengage.com/

API Call Rate Limit

The default rate limits for each API endpoint is mentioned in the table below. An HTTP response code of 429 would be sent if you exceed these limits.

EndpointRate Limit
User Data Update5,000 per minute
Event Data Update5,000 per minute
Creating Business Events1 per minute
Transactional Campaign API Request100 per minute

You will also get the following headers in the response for you to programmatically keep a track of the limits:

Header NameWhat It MeansSample Value
X-RateLimit-LimitThe per minute API rate limit for that endpoint5000
X-RateLimit-RemainingHow many more requests you can make in that minute4990

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.

CodeWhat It MeansHow to Resolve
400Invalid resource/parametersStep 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, /survey/response/

Step 2: Please drop in a few lines at [email protected] if the issue persists.
401Invalid authentication/access | Unauthorized accessStep 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.
404Invalid URLStep 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!