This destination is available only to Adobe Real-Time Customer Data Platform Ultimate customers.
The HTTP API destination is an Adobe Experience Platform streaming destination that helps you send profile data to third-party HTTP endpoints.
To send profile data to HTTP endpoints, you must first connect to the destination in Adobe Experience Platform.
The HTTP API destination allows you to export XDM profile data and audiences to generic HTTP endpoints. There, you can run your own analytics or perform any other operations you may need on profile data exported out of Experience Platform.
HTTP endpoints can be either customers’ own systems or third-party solutions.
This section describes which types of audiences you can export to this destination.
Audience origin | Supported | Description |
---|---|---|
Segmentation Service | ✓ | Audiences generated through the Experience Platform Segmentation Service. |
Custom uploads | ✓ | Audiences imported into Experience Platform from CSV files. |
Refer to the table below for information about the destination export type and frequency.
Item | Type | Notes |
---|---|---|
Export type | Profile-based | You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), as chosen in the mapping screen of the destination activation workflow. |
Export frequency | Streaming | Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations. |
To use the HTTP API destination to export data out of Experience Platform, you must meet the following prerequisites:
You can also use Adobe Experience Platform Destination SDK to set up an integration and send Experience Platform profile data to an HTTP endpoint.
You can use Mutual Transport Layer Security (mTLS) to ensure enhanced security in outbound connections to your HTTP API destination connections.
mTLS is an end-to-end security method for mutual authentication that ensures that both parties sharing information are who they claim to be before data is shared. mTLS includes an additional step compared to TLS, in which the server also asks for the client’s certificate and verifies it at their end.
If you want to use mTLS with HTTP API destinations, the server address you put in the destination details page must have TLS protocols disabled and only mTLS enabled. If the TLS 1.2 protocol is still enabled on the endpoint, no certificate is sent for the client authentication. This means that to use mTLS with your HTTP API destination, your “receiving” server endpoint must be an mTLS-only enabled connection endpoint.
If you want to check the Common Name (CN) and Subject Alternative Names (SAN) to do additional third-party validation, you can download the certificate below:
You can also securely retrieve public certificates by making a GET request to the MTLS endpoint. See the public certificate endpoint documentation for more information.
To meet customers’ security and compliance requirements, Experience Platform provides a list of static IPs that you can allowlist for the HTTP API destination. Refer to IP address allowlist for streaming destinations for the complete list of IPs to allowlist.
The HTTP API destination supports several authentication types to your HTTP endpoint:
curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'
To connect to the destination, you need the View Destinations and Manage Destinations access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.
To connect to this destination, follow the steps described in the destination configuration tutorial. When connecting to this destination, you must provide the following information:
If you select the Bearer token authentication type to connect to your HTTP endpoint, input the fields below and select Connect to destination:
If you select the None authentication type to connect to your HTTP endpoint:
When you select this authentication open, you only need to select Connect to destination and the connection to your endpoint is established.
If you select the OAuth 2 Password authentication type to connect to your HTTP endpoint, input the fields below and select Connect to destination:
If you select the OAuth 2 Client Credentials authentication type to connect to your HTTP endpoint, input the fields below and select Connect to destination:
Authorization
header after being base64 encoded and sent to your destination. For an example, see the Supported authentication types section.To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.
header1:value1,header2:value2,...headerN:valueN
.parameter1=value¶meter2=value
.You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.
When you are finished providing details for your destination connection, select Next.
See Activate audience data to streaming profile export destinations for instructions on activating audiences to this destination.
In the Select attributes step, Adobe recommends that you select a unique identifier from your union schema. Select the unique identifier and any other XDM fields that you want to export to the destination.
Experience Platform optimizes the profile export behavior to your HTTP API destination, to only export data to your API endpoint when relevant updates to a profile have occurred following audience qualification or other significant events. Profiles are exported to your destination in the following situations:
In all the cases described above, only the profiles where relevant updates have occurred are exported to your destination. For example, if an audience mapped to the destination flow has a hundred members, and five new profiles qualify for the segment, the export to your destination is incremental and only includes the five new profiles.
Note that all the mapped attributes are exported for a profile, no matter where the changes lie. So, in the example above all the mapped attributes for those five new profiles will be exported even if the attributes themselves haven’t changed.
Regarding the data that is exported for a given profile, it is important to understand the two different concepts of what determines a data export to your HTTP API destination and which data is included in the export.
What determines a destination export | What is included in the destination export |
---|---|
|
|
For example, consider this dataflow to an HTTP destination where three audiences are selected in the dataflow, and four attributes are mapped to the destination.
A profile export to the destination can be determined by a profile qualifying for or exiting one of the three mapped segments. However, in the data export, in the segmentMembership
object (see Exported Data section below), other unmapped audiences might appear, if that particular profile is a member of them and if these share the same merge policy as the audience that triggered the export. If a profile qualifies for the Customer with DeLorean Cars segment but is also a member of the Watched “Back to the Future” movie and Science fiction fans segments, then these other two audiences will also be present in the segmentMembership
object of the data export, even though these are not mapped in the dataflow, if these share the same merge policy with the Customer with DeLorean Cars segment.
From a profile attributes point of view, any changes to the four attributes mapped above will determine a destination export and any of the four mapped attributes present on the profile will be present in the data export.
When you add a new audience to an existing destination, or when you create a new destination and map audiences to it, Experience Platform exports historical audience qualification data to the destination. Profiles which qualified for the audience before the audience was added to the destination are exported to the destination within approximately one hour.
Your exported Experience Platform data lands in your HTTP destination in JSON format. For example, the export below contains a profile that has qualified for a certain segment, is a member of another two segments, and exited another segment. The export also includes the profile attribute first name, last name, date of birth, and personal email address. The identities for this profile are ECID and email.
{
"person": {
"birthDate": "YYYY-MM-DD",
"name": {
"firstName": "John",
"lastName": "Doe"
}
},
"personalEmail": {
"address": "john.doe@acme.com"
},
"segmentMembership": {
"ups":{
"7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
"lastQualificationTime":"2022-01-11T21:24:39Z",
"status":"exited"
},
"59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
"lastQualificationTime":"2022-01-02T23:37:33Z",
"status":"realized"
},
"947c1c46-008d-40b0-92ec-3af86eaf41c1":{
"lastQualificationTime":"2021-08-25T23:37:33Z",
"status":"realized"
},
"5114d758-ce71-43ba-b53e-e2a91d67b67f":{
"lastQualificationTime":"2022-01-11T23:37:33Z",
"status":"realized"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
Below are further examples of exported data, depending on the UI settings you select in the connect destination flow for the Include Segment Names and Include Segment Timestamps options:
segmentMembership
section"segmentMembership": {
"ups": {
"5b998cb9-9488-4ec3-8d95-fa8338ced490": {
"lastQualificationTime": "2019-04-15T02:41:50+0000",
"status": "realized",
"createdAt": 1648553325000,
"updatedAt": 1648553330000,
"mappingCreatedAt": 1649856570000,
"mappingUpdatedAt": 1649856570000,
"name": "First name equals John"
}
}
}
segmentMembership
section"segmentMembership": {
"ups": {
"5b998cb9-9488-4ec3-8d95-fa8338ced490": {
"lastQualificationTime": "2019-04-15T02:41:50+0000",
"status": "realized",
"createdAt": 1648553325000,
"updatedAt": 1648553330000,
"mappingCreatedAt": 1649856570000,
"mappingUpdatedAt": 1649856570000,
}
}
}
In 95 percent of the time, Experience Platform attempts to offer a throughput latency of less than 10 minutes for successfully sent messages with a rate of less than 10 thousand requests per second for each dataflow to an HTTP destination.
In case of failed requests to your HTTP API destination, Experience Platform stores the failed requests and retries twice to send the requests to your endpoint.