Develop your own WEB API

The Dengage Platform can invoke your Custom Web APIs during the audience export process. This section outlines the format of the data sent by the Dengage Platform, providing the necessary details for you to develop a function that receives and processes this data.

👍

Using WEB APIs

When developed, WEB APIs are being used in DataSpace > Export module, Automated Flow > Export Node and Campaign > Flow > Export nodes.

Functionality

The web API call, when used in conjunction with the Export process, facilitates the transfer of datasets generated by the export. This transfer is accomplished through HTTP requests in accordance with the contract specified below, targeting endpoints that are defined during the remote target setup.

How to make a WEB API definition through Remote Target interface

Please refer to Remote Targets documentation to understand how we can create a WEB API Remote Target to export audience data to.

🚧

You need to develop your WEB API first

Please note that you need to read this section and develop your own WEB API to receive audiences from the Dengage Platform when configured. The part below explains the format of the data that the Dengage Platform will send to a WEB API call when configured through the Platform's Export interface.

👍

Authentication and HTTP2 gzip

Authentication: The remote target web API may use Basic Authentication as an authentication mechanism. This is optional.

Performance Enhancements: Settings for HTTP2 and gzip compression are available to minimize data transfer. If enabled, endpoints must be prepared to handle HTTP2 requests and decompress data according to gzip settings.

These options are set in Remote Targets configuration page while you define a WEB API Remote Target to the platform.

Web API Call JSON Model

This section details the format of the data outputted by the Dengage Platform when an Export is configured to target a WEB API.

Method: POST. This is the type of the request.

Payload: This is an example of the payload format that our services will output as configured. You will need to accommodate this data format in your web service.

{
    "exportName": "configured_name_of_the_export",
    "batchId": 1,
    "data": [
        {
            "contact_key": "contact 1",
            "field2": "value20",
            "field3": "value30",
            "field4": "value40"
        },
        {
            "field1": "value11",
            "field2": "value21",
            "field3": "value31",
            "field4": "value41"
        }
    ]
}

Parameters

  • exportName: The name input by the user in the admin panel during the setup of the export operation. This name helps identify incoming data in the developed web API.
  • batchId: When the dataset exceeds 1000 rows at the time of execution, the system segments these rows into chunks of a thousand. These chunks are posted to the web API endpoint in parallel. The same batch ID persists in the post requests within a particular execution period to differentiate the data from that sent in other periods.
  • data: An array of key-value pairs. The fields in each element are configured automatically based on the selected or specified query during the export process. Each request can include up to 1000 rows.

Example

For an Export operation derived from the following SQL query:

Select contact_key, gender from master_contact limit 2;

The example payload to be posted to the web service will look like this:

{
    "exportName": "Example Query",
    "batchId": 1,
    "RowList": [
        {
            "contact_key": "contact 1",
            "gender": "female"
        },
        {
            "contact_key": "contact 2",
            "gender": "male"
        }
    ]
}

This model illustrates how data is structured and transmitted to support efficient data management and integration using web APIs.