Bulk Data Insertion API endpoints

Once you have met all prerequisites, have a correctly formatted file and have checked your file for syntax errors with our validation tool, you can begin making API calls to Adobe's ingestion endpoint for this API.

Adobe may add optional request and response members (name/value pairs) to existing API objects at any time and without notice or changes in versioning. Adobe recommends that you refer to the API documentation of any third-party tool you integrate with our APIs so that such additions are ignored in processing if not understood. If implemented properly, such additions are non-breaking changes for your implementation. Adobe will not remove parameters or add required parameters without first providing standard notification through release notes.

Primary ingestion endpoint

The file ingestion endpoint is found here.

POST https://analytics-collection.adobe.io/aa/collect/v1/events

Include all of the required headers with each API call:

Authorization: Required for authentication with the API. Format is the string "Bearer {ACCESS_TOKEN}.
x-api-key: Required for authentication with the API. Found in the Adobe Developer console under the JWT service credentials as "Client ID".
x-adobe-vgid: Required for this endpoint. The visitor group ID. See Visitor groups.
x-adobe-idempotency-key: Optional. Allows you to store a reference to your unique file identifier for the upload. This value can be used for duplication protection in cases when your request does not return a response from Adobe.

You must also add the file, which should be compressed in gzip format, and included as multipart/form-data.

The https://analytics-collection.adobe.io domain automatically routes your API call to the best region for processing. However, if you are legally required to have your data processed in a specific part of the world, you can use one of the following regional host names for API calls:

US processing: https://analytics-collection-us.adobe.io
European processing: https://analytics-collection-eu.adobe.io

Request

Response

curl -X POST -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-adobe-vgid: example_group" \
    -F file=@/tmp/ingest_file.gz \
    "https://analytics-collection.adobe.io/aa/collect/v1/events"
Copied to your clipboard
curl -X POST -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-adobe-vgid: example_group" \
    -F file=@/tmp/ingest_file.gz \
    "https://analytics-collection.adobe.io/aa/collect/v1/events"

{
  "file_id": "5c04f400-fca5-420c-9c36-b94aaec55e69",
  "visitor_group_id": "example_group",
  "size": 355600,
  "received_date": 1506553535,
  "rows": 10000,
  "invalid_rows": 42,
  "upload_name": "ingest_file.gz",
  "status": "string",
  "status_code": "UPLOADED",
  "processing_log": "string",
  "idempotency_key": "5c04f400-fca5-420c-9c36-b94aaec55e69"
}
Copied to your clipboard
{
  "file_id": "5c04f400-fca5-420c-9c36-b94aaec55e69",
  "visitor_group_id": "example_group",
  "size": 355600,
  "received_date": 1506553535,
  "rows": 10000,
  "invalid_rows": 42,
  "upload_name": "ingest_file.gz",
  "status": "string",
  "status_code": "UPLOADED",
  "processing_log": "string",
  "idempotency_key": "5c04f400-fca5-420c-9c36-b94aaec55e69"
}

Response object details

When you upload a file to this endpoint, Adobe returns a JSON object that can contain the following fields:

Field	Data type	Description
`file_id`	string	Unique identifier for the file upload transaction. Automatically generated by Adobe unless you include the `x-adobe-idempotency-key` header in the API call.
`visitor_group`	string	Name of the visitor group as stated in the `x-adobe-vgid` header. See Visitor groups.
`size`	long	The size of the uploaded file in bytes.
`received_date`	long	The Unix timestamp when the file was received
`rows`	integer	The number of rows contained in the file
`invalid_rows`	integer	The number of invalid rows identified in the file
`upload_name`	string	The name of the file included in the request
`status`	string	More verbose details around the `status_code`
`status_code`	string	The status of the file upload. Valid values include `UPLOADED` or `REJECTED`.
`processing_log`	string	Details around specific issues encountered. If an error type has 10 or less problem rows, they are explicitly mentioned. If an error type has more than 10 problem rows, summarized results are provided.
`idempotency_key`	string	Either the value of the `x-adobe-idempotency-key` if supplied, or the `file_id`

Validate

Before uploading your first file, Adobe strongly recommends running the file through the validation endpoint. Please note, you should not send EVERY file to this endpoint. This endpoint exists to validate file format before you begin uploading them to the events endpoint. Files uploaded to this endpoint are not stored on Adobe's servers or processed. This API is synchronous and returns an immediate reply that states the file's validation status. If a file fails validation, the reason is also returned. See Troubleshoot uploads for more information.

POST https://analytics-collection.adobe.io/aa/collect/v1/events/validate

Request

Success response

Failure response - invalid rows

curl -X POST -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-adobe-vgid: example_group" \
    -F file=@/tmp/ingest_file.gz \
    "https://analytics-collection.adobe.io/aa/collect/v1/events/validate"
Copied to your clipboard
curl -X POST -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-adobe-vgid: example_group" \
    -F file=@/tmp/ingest_file.gz \
    "https://analytics-collection.adobe.io/aa/collect/v1/events/validate"

{
    "success": "File is valid"
}
Copied to your clipboard
{
    "success": "File is valid"
}

{
    "error": "File has 2 rows that do not conform to the required CSV format! (Ex: row #59)"
}
Copied to your clipboard
{
    "error": "File has 2 rows that do not conform to the required CSV format! (Ex: row #59)"
}

Idempotency Key Lookup

The API offers duplication protection through the use of an idempotency_key. This unique value is generated on the client side, then passed in through the x-adobe-idempotency-key header field. If your POST request submission does not return a response, you can call this lookup endpoint to verify if the file was received by Adobe.

If you do not include an idempotency key when creating a file upload, it defaults to the file_id generated when uploading a file. Since this idempotency key is generated after a file is uploaded, automatically generated idempotency keys lose their effectiveness in preventing duplicate uploads.

GET https://analytics-collection.adobe.io/aa/collect/v1/events/key/{idempotency_key}

Request

Success response

Failure response

curl -X GET -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    "https://analytics-collection.adobe.io/aa/collect/v1/events/key/{IDEMPOTENCY_KEY}"
Copied to your clipboard
curl -X GET -H "accept: application/json" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    -H "x-api-key: {CLIENTID}" \
    "https://analytics-collection.adobe.io/aa/collect/v1/events/key/{IDEMPOTENCY_KEY}"

{
    "file_id": "22eea6b6-eecf-4d13-b70f-abbb8a81efa2",
    "size": 1687458,
    "received_date": 1650323049,
    "rows": 10212,
    "idempotency_key":"{IDEMPOTENCY_KEY}"
}
Copied to your clipboard
{
    "file_id": "22eea6b6-eecf-4d13-b70f-abbb8a81efa2",
    "size": 1687458,
    "received_date": 1650323049,
    "rows": 10212,
    "idempotency_key":"{IDEMPOTENCY_KEY}"
}

{
    "error": "File not found"
}
Copied to your clipboard
{
    "error": "File not found"
}

File format

Visitor groups

Last updated 2/27/2024

Was this helpful?

Yes

Bulk Data Insertion API endpoints

Primary ingestion endpoint.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Response object details.css-jmmyhj{margin-left:var(--spectrum-global-dimension-size-50);}

Validate

Idempotency Key Lookup

Primary ingestion endpoint

Response object details