Profile import

Profile Import API

Important

Feature availability is part of a phased rollout. Your organization may not see this functionality yet. It will become available when your environment is included in the rollout.

The Profile Import API lets you upload a data file, monitor batch progress, and download results. All endpoints use the base path /v1/batches.

Authentication

All Profile Import API requests require a static API key in the Authorization header:

Authorization: ApiKey <your-api-key>

To create an API key, see Create an API key.

Base URL

To find your base URL, open SitecoreAI and click Performance > Settings > Profile import > Credentials. Use the API Endpoint value as {base_url} in API requests. All requests follow the pattern {base_url}/v1/batches/....

Endpoints

Method	Path	Description
`POST`	`/v1/batches`	Upload a profile batch file.
`GET`	`/v1/batches/{batchId}/status`	Check the status of a batch.
`GET`	`/v1/batches/{batchId}/stats`	Get detailed statistics for a completed batch.
`GET`	`/v1/batches/{batchId}/results`	Download the results file for a completed batch.
`GET`	`/v1/batches`	List all batches for your environment.

Upload a profile batch file

Uploads a JSONL file containing profile records for processing.

Endpoint: POST /v1/batches

Content type: multipart/form-data

Form parts:

Part	Type	Required	Description
`file`	Binary	Yes	The JSONL file to process. Maximum 100 MB.
`md5`	String	Yes	The MD5 checksum of the file as a 32-character hexadecimal string. The server computes its own MD5 and rejects the upload if the values don't match. See Compute the MD5 checksum of the JSONL file.

Example request:

curl -X POST "{base_url}/v1/batches" \
  -H "Authorization: ApiKey <your-api-key>" \
  -F "[email protected]" \
  -F "md5=01556b1dcc2b3cb87889838ee349357a"

Success response: 202 Accepted

{
    "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a",
    "status": "QUEUED",
    "checksumMd5": "01556b1dcc2b3cb87889838ee349357a",
    "fileSizeBytes": 1873,
    "createdAt": "2026-07-02T13:14:36.546433Z"
}

Note

The API returns HTTP 202 Accepted, not 201 Created. The batch is queued for processing and has not been processed yet.

Error responses:

Status	Cause
`400 Bad Request`	Invalid `md5` format, MD5 checksum mismatch, empty file, or mapping spec exceeds 10,000 characters.
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	The API key is not authorized to upload batch files.
`429 Too Many Requests`	Queue limit reached. A batch is already queued or running for this environment.

Check batch status

Returns the current status of a batch.

Endpoint: GET /v1/batches/{batchId}/status

Example request:

curl "{base_url}/v1/batches/{batchId}/status" \
  -H "Authorization: ApiKey <your-api-key>"

Response:

{
    "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a",
    "status": "COMPLETED_WITH_ERRORS",
    "totalRecords": 12,
    "succeededRecords": 6,
    "failedRecords": 6,
    "processingTimeSeconds": 64,
    "startedProcessingAt": "2026-07-02T13:14:39.064400Z",
    "finishedProcessingAt": "2026-07-02T13:15:43.475259Z"
}

The status field contains one of the following values: QUEUED, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, or FAILED. For a description of each state, see Batch states.

Error responses:

Status	Cause
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	The API key is not authorized to perform this operation.
`404 Not Found`	Batch not found.

Get batch statistics

Returns detailed statistics for a batch, including record counts and error breakdowns. Statistics are available after the batch reaches a final state (COMPLETED, COMPLETED_WITH_ERRORS, or FAILED).

Endpoint: GET /v1/batches/{batchId}/stats

Example request:

curl "{base_url}/v1/batches/{batchId}/stats" \
  -H "Authorization: ApiKey <your-api-key>"

Response:

{
    "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a",
    "status": "COMPLETED_WITH_ERRORS",
    "checksumMd5": "01556b1dcc2b3cb87889838ee349357a",
    "fileSizeBytes": 1873,
    "totalRecords": 12,
    "succeededRecords": 6,
    "createdRecords": 3,
    "updatedRecords": 3,
    "failedRecords": 6,
    "failedByCode": {
        "INVALID_RECORD": {
            "count": 6,
            "firstRecordIndex": 6,
            "firstDescription": "No identifier with a valid id and a recognised provider"
        }
    },
    "processingTimeSeconds": 64,
    "createdBy": "[email protected]",
    "createdAt": "2026-07-02T13:14:36.546433Z",
    "startedProcessingAt": "2026-07-02T13:14:39.064400Z",
    "finishedProcessingAt": "2026-07-02T13:15:43.475259Z"
}

Response fields:

Field	Description
`batchId`	The unique identifier for the batch.
`status`	The current batch status.
`checksumMd5`	The MD5 checksum of the uploaded file.
`fileSizeBytes`	The size of the uploaded file in bytes.
`totalRecords`	Total number of records in the input file.
`succeededRecords`	Number of records processed successfully.
`createdRecords`	Number of new profiles created.
`updatedRecords`	Number of existing profiles updated.
`failedRecords`	Number of records that failed processing.
`failedByCode`	Breakdown of failures by error code, with the count, first failing record index, and a description.
`processingTimeSeconds`	Total processing time in seconds.
`createdBy`	The user who uploaded the batch.
`createdAt`	When the batch was uploaded.
`startedProcessingAt`	When processing began.
`finishedProcessingAt`	When processing completed.

Error responses:

Status	Cause
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	The API key is not authorized to perform this operation.
`404 Not Found`	Batch not found.

Download results

Downloads the results file for a completed batch. The file is in JSONL format, with one line per input record. Each line contains the record's outcome, and for successful records, the resolved profile ID. Failed records include an error code and description.

For the output format, see Output file format. For a description of error codes, see Record-level error codes.

Endpoint: GET /v1/batches/{batchId}/results

Example request:

curl "{base_url}/v1/batches/{batchId}/results" \
  -H "Authorization: ApiKey <your-api-key>" \
  -o results.jsonl

Response: 200 OK with JSONL file stream.

Error responses:

Status	Cause
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	The API key is not authorized to perform this operation.
`404 Not Found`	The batch has not reached a final state, or no results file exists.

List batches

Returns a paginated list of all batches for your environment.

Endpoint: GET /v1/batches

Query parameters:

Parameter	Type	Default	Description
`page`	Integer	`1`	The page number (1-based).
`pageSize`	Integer	`20`	The number of items per page. Maximum `100`.

Example request:

curl "{base_url}/v1/batches?page=1&pageSize=10" \
  -H "Authorization: ApiKey <your-api-key>"

Response:

{
    "items": [
        {
            "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a",
            "status": "COMPLETED_WITH_ERRORS",
            "totalRecords": 12,
            "succeededRecords": 6,
            "failedRecords": 6,
            "processingTimeSeconds": 64,
            "createdAt": "2026-07-02T13:14:36.546433Z",
            "startedProcessingAt": "2026-07-02T13:14:39.064400Z",
            "finishedProcessingAt": "2026-07-02T13:15:43.475259Z"
        },
        {
            "batchId": "91bdceae-6976-45a7-8f26-677bf4116b68",
            "status": "COMPLETED",
            "totalRecords": 2,
            "succeededRecords": 2,
            "failedRecords": 0,
            "processingTimeSeconds": 49,
            "createdAt": "2026-07-01T14:55:02.045642Z",
            "startedProcessingAt": "2026-07-01T14:55:07.329795Z",
            "finishedProcessingAt": "2026-07-01T14:55:56.764775Z"
        },
        {
            "batchId": "33eb7473-3ff2-47d3-9ceb-ddb5fdd07cf9",
            "status": "COMPLETED_WITH_ERRORS",
            "totalRecords": 3,
            "succeededRecords": 2,
            "failedRecords": 1,
            "processingTimeSeconds": 55,
            "createdAt": "2026-07-01T14:45:45.997098Z",
            "startedProcessingAt": "2026-07-01T14:45:46.828330Z",
            "finishedProcessingAt": "2026-07-01T14:46:41.787527Z"
        },
        {
            "batchId": "7f39f6b1-f7e5-49bc-955c-708c20557839",
            "status": "COMPLETED_WITH_ERRORS",
            "totalRecords": 3,
            "succeededRecords": 2,
            "failedRecords": 1,
            "processingTimeSeconds": 74,
            "createdAt": "2026-07-01T14:00:08.664819Z",
            "startedProcessingAt": "2026-07-01T14:00:12.552876Z",
            "finishedProcessingAt": "2026-07-01T14:01:26.840059Z"
        },
        {
            "batchId": "28658e45-c699-4137-ae6e-60dfe2005f25",
            "status": "COMPLETED_WITH_ERRORS",
            "totalRecords": 3,
            "succeededRecords": 2,
            "failedRecords": 1,
            "processingTimeSeconds": 49,
            "createdAt": "2026-05-28T08:35:24.992253Z",
            "startedProcessingAt": "2026-05-28T08:35:29.256079Z",
            "finishedProcessingAt": "2026-05-28T08:36:18.406057Z"
        },
        {
            "batchId": "40d75117-ba76-49db-954c-fbcd0d6182fe",
            "status": "FAILED",
            "processingTimeSeconds": 35,
            "createdAt": "2026-05-14T12:46:38.023267Z",
            "startedProcessingAt": "2026-05-14T12:47:58.542964Z",
            "finishedProcessingAt": "2026-05-14T12:48:33.587373Z"
        },
        {
            "batchId": "702212d0-1854-40d7-a264-fbe4c93ed7a6",
            "status": "FAILED",
            "processingTimeSeconds": 40,
            "createdAt": "2026-05-14T12:33:22.752706Z",
            "startedProcessingAt": "2026-05-14T12:34:43.494472Z",
            "finishedProcessingAt": "2026-05-14T12:35:23.517042Z"
        },
        {
            "batchId": "30a1fec3-1b89-435a-8be2-b007c6e7351a",
            "status": "FAILED",
            "processingTimeSeconds": 40,
            "createdAt": "2026-05-13T09:48:39.960300Z",
            "startedProcessingAt": "2026-05-13T09:50:18.926490Z",
            "finishedProcessingAt": "2026-05-13T09:50:58.863310Z"
        }
    ],
    "page": 1,
    "pageSize": 10,
    "totalItems": 8
}

Response fields:

Field	Description
`items`	Array of batch summary objects. Each item contains the following fields: `batchId`, `status`, `totalRecords`, `succeededRecords`, `failedRecords`, `processingTimeSeconds`, `createdAt`, `startedProcessingAt`, `finishedProcessingAt`. For batches with a `FAILED` status, the `totalRecords`, `succeededRecords`, and `failedRecords` fields are omitted.
`page`	The current page number (1-based).
`pageSize`	The number of items returned per page.
`totalItems`	The total number of batches for your environment across all pages.

Error responses:

Status	Cause
`400 Bad Request`	Invalid pagination parameters.
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	The API key is not authorized to perform this operation.

If you have suggestions for improving this article, let us know!