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.
`operationType`	String	No	The operation to perform: `UPSERT` (default, if omitted) to create or update profiles, or `DELETE` to delete profiles. Case-sensitive. Any other value is rejected. See Delete profiles in bulk.

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, mapping spec exceeds 10,000 characters, or `operationType` is present but set to a value other than `UPSERT` or `DELETE`.
`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.

Delete profiles in bulk

Set operationType to DELETE to permanently delete profiles instead of creating or updating them. Each record in the file must use "recordType": "PROFILE_DELETION" and an identifiers array. Deletion records don't use contact or extensions. For the record format, including identifier requirements, see Deletion records.

Warning

Deletion is a permanent, unrecoverable hard delete. Submitting a batch with operationType=DELETE requires the same authorization as uploading an import batch. There is no separate permission for deletion, so make sure to control access to your API keys carefully.

Example request:

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

The response has the same shape as a regular upload and doesn't indicate the operation type. To confirm that a batch was processed as a deletion, check deletedRecords and notFoundRecords in the batch statistics after processing completes.

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 for an import batch (operationType=UPSERT):

{
    "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a",
    "status": "COMPLETED_WITH_ERRORS",
    "checksumMd5": "01556b1dcc2b3cb87889838ee349357a",
    "fileSizeBytes": 1873,
    "totalRecords": 12,
    "succeededRecords": 6,
    "createdRecords": 3,
    "updatedRecords": 3,
    "deletedRecords": null,
    "notFoundRecords": null,
    "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 for a deletion batch (operationType=DELETE):

{
    "batchId": "91bdceae-6976-45a7-8f26-677bf4116b68",
    "status": "COMPLETED_WITH_ERRORS",
    "checksumMd5": "6a1e2f9c8b3d4e5f6a7b8c9d0e1f2a3b",
    "fileSizeBytes": 957,
    "totalRecords": 8,
    "succeededRecords": 6,
    "createdRecords": null,
    "updatedRecords": null,
    "deletedRecords": 6,
    "notFoundRecords": 1,
    "failedRecords": 1,
    "failedByCode": {
        "INVALID_RECORD": {
            "count": 1,
            "firstRecordIndex": 1,
            "firstDescription": "Missing, null, or non-array 'identifiers' field"
        }
    },
    "processingTimeSeconds": 50,
    "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. For a deletion batch, this equals `deletedRecords`; `notFoundRecords` isn't counted as succeeded or failed.
`createdRecords`	Number of new profiles created. `null` for a deletion batch.
`updatedRecords`	Number of existing profiles updated. `null` for a deletion batch.
`deletedRecords`	Number of profiles deleted. `null` unless the batch was uploaded with `operationType=DELETE`.
`notFoundRecords`	Number of records whose identifiers didn't match any profile. `null` unless the batch was uploaded with `operationType=DELETE`.
`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 a deletion batch, each line reports whether the profile was deleted or not found instead.

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!