Web API Call

A Web API (Application Programming Interface) allows different software systems to communicate with each other over the web. It defines a set of rules and protocols for building and interacting with software applications.

The Web API Call node allows you to to transfer data from D-Engage to your own systems or third-party services via a defined API endpoint.

Processing Limits and Behavior

How Data is Sent

The Web API Call feature processes data in batches of 1,000 records. Each batch is sent as a separate request, and these requests are executed in parallel as multi-tasks. This ensures efficient and scalable data transfer, especially for large audiences.

When a Web API Call is executed, the selected audience is automatically divided into batches of 1,000 records. Each batch is converted into a JSON payload and sent to the configured Web API endpoint as a separate HTTP POST request.

For example, an audience of 600,000 contacts is processed as 600 individual HTTP POST requests, each containing approximately 1,000 records.

How Requests Are Processed

The Web API Call feature does not use a fixed request rate, such as "1 request per second." Instead, requests are processed continuously in parallel, allowing multiple batches to be sent at the same time. As requests are completed, the remaining batches continue processing until all requests have been sent.

Because of this, the total processing time primarily depends on the response time of the destination Web API endpoint. Faster endpoints complete processing more quickly, while slower response times, network latency, throttling, or server errors increase the overall duration.

Error Handling

If a batch receives an HTTP response other than 200, 201, 202, 203, or 204, that batch is considered unsuccessful.

Failed batches are not automatically retried. Instead, the error is logged, and processing continues with the remaining batches. A failed batch does not stop the rest of the audience from being sent.

Processing Summary

Define a Remote Target for Web API Calls

Before using the Web API Call node in your campaign flow, you must first define a Remote Target. This tells the system where to send your API requests.

How to Define a Remote Target for Web API

1. Navigate to Settings Go to Settings > Integrations > Remote Targets in the D·engage interface.
2. Add a New Remote Target Click the Add button to start the setup.
3. Fill in the Required Fields Complete the form with the following details:

• Name: Enter a unique name for the remote target. This name will be used when selecting the API target in the campaign flow.
• Type: Select Web API from the connection type dropdown.
• Base URL: Enter the base URL of your API
• Endpoint: Specify the exact endpoint you want to call, such as: /bulkupsert
• Authentication Type: Choose the appropriate authentication type. If your API doesn't require authentication, select None (default). For APIs that do require it, you can choose Basic.

4. Save Click Save to complete the setup. Your Remote Target is now available and can be selected when configuring the Web API Call node in your campaign journey.

Set Up the Web API in Your Campaign Flow

Create a New Campaign Flow

1. Navigate to Campaigns > Flow in the platform.
2. Create a new campaign, selecting either one-time or recurring as needed.

Add the Web API Node

1. From the Actions panel on the left, find the Web API node.
2. Drag and drop the Web API node into your campaign flow.

Configure the Web API Node

1. Double-click the Web API node to open the configuration modal.
2. Select your Remote Target from the available list.

3. Provide a name for this export. This can be any name you prefer for internal reference.

Define the Data to Export

1. In the next screen, choose the columns to send to the selected Remote Target.
2. You can include:
   • Custom Columns
   • Columns from your campaign table
   • Columns from your master_contact or master_device table

Note:

• The system requires and automatically includes contact_key (for master_contact) or device_id (for master_device).
• These fields are pre-selected and cannot be unchecked.
• If there are any column name conflicts (e.g., duplicate names across tables), the system will automatically rename them to prevent errors.

Review and Finalize

1. On the final screen, you’ll see a summary along with a sample cURL request for reference.

The exported JSON output will consist of two main parts:

• CampaignParameters: Contains system-generated metadata fields like CampaignId, CampaignName, CampaignInstanceStartTime, DeliveryTime, SendId, and SendName.
• RowList: Includes:
  • Your custom key-value pairs (repeated for each row)
  • Data from the campaign table (if used as the audience source)
  • Data from the master_contact or master_device table (including required fields like contact_key or device_id)

Save and Finalize

• Click Save to complete the configuration.
• The node in the campaign flow will update to reflect your Web API setup.

Tips and Best Practices

Ensure your endpoint is properly configured to receive data in the specified JSON format. Regularly update your API endpoint to accommodate any changes in data structure or requirements. Use descriptive names for your custom parameters to maintain clarity and ease of use.