1. Profile import

Import a batch file

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.

In this walkthrough, you upload a JSONL file to the Profile Import API, track it through to completion, and view the results.

This walkthrough describes how to:

  1. Create an API key
  2. Prepare your JSONL file
  3. Compute the MD5 checksum
  4. Upload the file
  5. Monitor the batch
  6. View the results
Before you begin
  • You have a JSONL file ready to upload. See batch file format for formatting requirements.
  • No other batch is currently QUEUED or RUNNING for your environment. Only one batch can be active at a time.

Create an API key

In production environments, you must authenticate using a static API key. You can create API keys from the Profile import page in SitecoreAI settings.

Note

In production environments, only Organization Owners and Organization Admins can create API keys. In non-production environments, all users can create API keys.

To create an API key:

  1. In SitecoreAI, click Performance > Settings > Profile import.

  2. Click the Credentials tab, and then click Create credential.

  3. Enter a name for the credential and an optional description.

  4. If you want the API key to expire after a year, then select Credential expires in 1 year. If you don't select this option, the API key does not expire.

  5. Click Create, then copy the API key. The key is displayed only one time and cannot be retrieved after you close the dialog.

Warning

Copy the API key before closing the dialog. You cannot retrieve it again after it disappears. If you lose it, you must create a new credential.

Prepare your JSONL file

Your input file must be UTF-8 encoded JSON Lines (JSONL) format, with one JSON object per line. Each line is an independent record that corresponds to a profile payload.

{"recordType":"profile","identifiers":[{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Alice1","lastName":"Smith2"}, "extensions":{"where": "In the wonderland"}}
{"recordType":"profile","identifiers":[{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Alice2","lastName":"Smith2"}, "extensions":{"where": "In the wonderland1"}}
{"recordType":"profile","identifiers":[{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Alice3","lastName":"Smith2"}, "extensions":{"where": "In the wonderland2"}}
{"recordType":"profile","identifiers":[{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Alice4","lastName":"Smith2"}, "extensions":{"where": "In the wonderland3"}}
{"recordType":"profile","identifiers":[{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Alice5","lastName":"Smith2"}, "extensions":{"where": "In the wonderland4"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0042"},{"provider":"email","id":"[email protected]"}],"contact":{"firstName":"Bob","lastName":"Jones"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}
{"recordType":"profile","identifiers":[{"provider":"userid","id":"crm-0044"}],"contact":{"firstName":"James","lastName":"Red"}}

For full formatting requirements, including the required identifiers structure and supported fields, see batch file format.

Tip

Keep file sizes under 100 MB. If your data set exceeds this limit, split it into multiple files and upload them one at a time, waiting for each batch to complete before starting the next.

Compute the MD5 checksum of the JSONL file

The API requires an MD5 checksum of your JSONL file to verify integrity during upload. Use one of the following methods to compute the MD5 hash before uploading:

md5sum guests.jsonl | awk '{print $1}'

The command outputs a 32-character hex string such as 01556b1dcc2b3cb87889838ee349357a. Copy this value. You pass it as the md5 form field when you upload through the API.

Upload the file

Note

In non-production environments, you can upload the file through the Profile import page, but in production environments, you must use the API.

Use a POST request with multipart/form-data to upload your file through the Profile Import API. Replace {base_url} with your API endpoint. You can find this on the Credentials tab of the Profile import page. Include your API key in the Authorization header.

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

A successful upload returns 202 Accepted with a batchId you use to track the batch:

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

Save the batchId. You'll use it to check status and download results.

Note

If you receive a 429 Too Many Requests error, a batch is already queued or running for your environment. Wait for it to finish before uploading a new file.

For a full list of error responses, see the Profile Import API.

Upload through the Profile import page (non-production only)

To upload a file through the SitecoreAI UI:

  1. In SitecoreAI, click Performance > Settings > Profile import.

  2. In the Uploads tab, click Upload batch.

  3. Select your JSONL file and click Upload.

After the upload completes, the batch appears in the Uploads tab where you can monitor its progress.

Monitor the batch

You can monitor the batch from the Profile import page, or poll the status endpoint using the batchId:

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

The response includes the current status and record counts:

{
    "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"
}

For a description of each state and retry behavior, see batch states.

View the results

After the batch reaches a final state (COMPLETED, COMPLETED_WITH_ERRORS, or FAILED), you can view the results in the Profile import page or use the stats endpoint to get a high-level overview of the import:

curl "{base_url}/v1/batches/7266232b-a7d4-496c-b0b3-be8dbde7495a/stats" \
  -H "Authorization: ApiKey <your-api-key>"

The response includes a summary of the import:

{
    "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"
}

You can also download the results to see the outcome for each record.

You have now successfully imported a batch file. You prepared a JSONL file, computed its MD5 checksum, uploaded it using the API, monitored processing, and retrieved the results.

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