Module guide: API call
Send an API call to your app
How it works
The module works very similarly to webhooks, but instead of triggering when a message is sent, it is used if any other conditions are met. You can send all user data to a specific URL.
For the "URL" field, enter the destination of the request, which could be another application or platform. The "Extra data (JSON)" field is for the data you wish to send in addition to the user's information.
How to use API call
To effectively leverage API calls for integrating your business processes with various applications, it's important to understand the process of data transfer. Here’s a breakdown of the key components involved in making an API call, using the example provided:
URL - in the URL section, you can specify your own endpoint to establish a connection with the selected application. You can also insert specific data points into the URL as query strings by using variable-value pairs (values can also be handled by snippet tags, but this is only possible with the HTTP - GET method).
Extra data (JSON) - this field lets you send detailed data in the JSON format. This input field supports the dynamic insertion of data through the snippet tags, offering flexibility in what you send. If you're using snippet tags within your JSON, ensure these are enclosed in quotes to avoid errors, as the format must be valid JSON syntax.
Exclude user info from call - this toggle feature gives you the option to exclude personal user data from the API call. By activating this, you prevent any additional user profile information, which otherwise would be automatically included, from being sent along with your API request.
Instead of sending the complete set of data as illustrated in the given example::
{
"path": 6,
"timestamp": "2021-02-01T07:27:44.469241+00:00",
"extra": {
"variable_1": "value_1"
},
"user": {
"id": 7,
"key": "x7NM5xw2eFxl",
"name": "John Doe",
"email": "johndoe@example.org",
"gender": "unknown",
"status": "visitor",
"phone_number": null,
"first_seen": "2021-01-07T13:33:24.576109Z",
"last_seen": "2021-01-07T13:33:24.604490Z",
"page_views": 1,
"last_ip": "99.99.99.99",
"timezone": "USA/DC",
"city": null,
"region": null,
"country": "USA",
"emails_enabled": true,
"browser_language": "en",
"score": 0,
"browser": "Chrome",
"os_type": "Mac OS X",
"resolution": "1440x900",
"created_at": "2021-01-07T13:33:24.585602Z",
"updated_at": "2021-01-12T15:08:07.917571Z",
"attributes": [],
"gravatar_url": null,
"lists": [],
"tags": [
{
"id": 16,
"name": "random_tag"
}
],
"notifications": true,
"facebook_url": null,
"linkedin_url": null,
"twitter_url": null,
"google_url": null,
"last_contacted": "2021-01-07T13:33:40.598000Z",
"user_id": "random_id"
}
}
you will able to send only the necessary data given in Extra data:
{
"path": 6,
"timestamp": "2021-02-01T07:34:23.815674+00:00",
"extra": {
"variable_1": "value_1"
}
}
The "Add header" option is essential when your API requests need authorization to connect with another application. In such instances, it's necessary to include specific headers like "Authorization" or "Content-Type", along with their respective values. To add additional headers, simply click the "Add header" button for each new header you need to include.
Trigger actions determined by response code
The API Call module includes the capability to trigger different actions in your automation flow depending on the response code received from the API call. Specifically, you can set actions to occur on successful responses (indicated by 2XX status codes) and actions for failures (indicated by 3XX, 4XX, or 5XX status codes).
On Success (2XX status codes): When the API call receives a response within the 2XX range, it means that the request was successfully received, understood, and accepted. In this scenario, you can connect subsequent actions that should occur as a result of a successful API call. This could involve moving the user along a specific path in the automation workflow, such as sending an email or updating a user attribute to reflect a successful interaction.
On Failure (3XX, 4XX, 5XX status codes): If the API call results in a response code in the 3XX range (redirection), 4XX range (client errors), or 5XX range (server errors), it indicates a failure to complete the request as intended. You can set up your automation to respond to these failures by triggering alternate actions. This could include sending a notification to you or adding some information to user profile (tag, attribute).
Case Study
Imagine you want to automate data transfer when someone signs up for a newsletter on your website. You send this information to User.com app as an event named "newsletter_register". To learn how to send events you can refer to this article on what are events and how to create them. Following the event, you update a user attribute called "newsletter_consent" to reflect their agreement.
To link this process with your web application—which in this example operates independently from your website—you'd employ the API Call module. First, connect the "newsletter_register" event trigger to the "Update an attribute" action. Following this update, the API call is connected and set up to dispatch the particular data to your web application's endpoint. This ensures that the user's action of signing up for a newsletter is automatically communicated to your web application.
