---
title: "Allocate batch upload location"
slug: "allocate-batch-upload-location"
abstract: "Describes how to allocate a batch upload location when uploading a batch file to Sitecore CDP."
---
# Allocate batch upload location

`PUT /v2/batches/<batchRef>`

Creates a location to which you subsequently [upload the batch file](https://doc.sitecore.com/cdp/en/developers/api/batch-api/upload-a-batch-file/upload-batch-file.html "Upload batch file").

| Attribute | Type | Description | Example |
| --- | --- | --- | --- |
| `batchRef` | string | The UUID of a batch upload.<br><br>This a UUID that you generate. It must be unique across all batches. You can [use online tools](https://guidgenerator.com/online-guid-generator.aspx) to generate a UUID. | `12af3453-62da-4b31-b646-631b7b5f3009` |

You must provide the following required attributes in the request body:

| Attribute | Type | Description | Example |
| --- | --- | --- | --- |
| `checksum` | string | A hex-encoded [MD5 checksum](https://emn178.github.io/online-tools/md5_checksum.html) for the gzipped file. This is to provide assurance that the integrity of the gzipped file is intact. | `"b1d600dbf7463924e24647e626cd7c1e"` |
| `size` | integer | The size in bytes of the gzipped file (`import.json.gz`). You can check this in the file's properties. | `227` |

In the response, in the `location` object, the `href` key contains the batch upload path. You use the batch upload path when you [upload the batch file](https://doc.sitecore.com/cdp/en/developers/api/batch-api/upload-a-batch-file/upload-batch-file.html "Upload batch file").

The response body contains the following fields:

| Attribute | Description | Type |
| --- | --- | --- |
| `href` | Echo back of the URL used in this request. | string |
| `ref` | UUID of the batch, forms part of the href. | string |
| `checksum` | Echo back of checksum of the uploading file. | string |
| `size` | Echo back of the size of the uploading file. | integer |
| `location` | Details of the file upload location. | object |
| `location.href` | The allocated URL to which you upload the batch file. This URL is valid for one hour. | string |
| `location.expiry` | Date and time that the upload location href expires. | date time |
| `status` | The status of the file upload. | object |
| `status.code` | The batch file processing status. Possible values:<br><br><ul><li>`uploading` - the batch reference is saved and the gzipped file can now be uploaded. The batch stays in this status until the file is fully uploaded. After receiving the file, Sitecore CDP validates it and changes the status to `file_uploaded`.</li><li>`file_uploaded` - Sitecore CDP received the gzipped file, and the file is now in the processing queue. This status is only available in the [inspect](https://doc.sitecore.com/cdp/en/developers/api/batch-api/upload-a-batch-file/retrieve-batch-file-upload-status.html) endpoint.</li><li>`processing` - Sitecore CDP is processing the gzipped file.</li><li>`success` - Sitecore CDP successfully processed all JSON records in the gzipped file. You can now [verify that CDP ingested the uploaded data](https://doc.sitecore.com/cdp/en/developers/api/batch-api/upload-a-batch-file.html#UUID-8ed431f9-8f85-ad6c-b8d9-b2927930b33a_section-idm1903352048250758).</li><li>`corrupted` - the MD5 checksum or the size of the gzipped file does not match the [values](https://doc.sitecore.com/cdp/en/developers/api/batch-api/upload-a-batch-file.html#UUID-8ed431f9-8f85-ad6c-b8d9-b2927930b33a_section-idm1903351892563384) provided by the developer.</li><li>`error` - Sitecore CDP did not process at least one JSON record in the gzipped file. You can download the error log to troubleshoot the issue. The location of the log file is the value of the `status.log` parameter.</li></ul> | string |
| `createdAt` | Date and time the request was created. | date time |
| `modifiedAt` | Date and time the request was last updated. | date time |

```curl
curl -X PUT '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
  "checksum": "b1d600dbf7463924e24647e626cd7c1e",
  "size": 227
}'

```

`location.href` contains the batch upload path:

```json
{
    "href": "<baseURL>/v2/batches/12af3453-62da-4b31-b646-631b7b5f3009",
    "ref": "12af3453-62da-4b31-b646-631b7b5f3009",
    "checksum": "b1d600dbf7463924e24647e626cd7c1e",
    "size": 227,
    "location": {
        "href": "https://sitecore-batch-service-production-eu-west-1.s3.eu-west-1.amazonaws.com/pqsTELpfrXBzxKozB0IoL4xuAT0s7WrH/12af3453-62da-4b31-b646-631b7b5f3009/import.gz?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEDAaCWV1LXdlc3QtMSJIMEYCIQCvLllsVnScVKunabp2ecWZ35wWC2qazGUOH38uZ4ebNwIhAPhKsvrNikvkBSJwFo4Heat72zODcLQCPzh87PRThE8qKtUECIn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNDkzNDAzOTY5MDY2IgzaKR3yFcEnGvR0NjEqqQQiccx7113xYh5boBVgjPQrzpcCLKgXi563nzp0YRIM52WE1LFEezlLQBEcRl9wo0i5ko5%2F8ne%2BPSFGxkc576fPqkdQzQyX9Ub1PA44pwuFzK%2FZSf9mHS7FRqPvvuxlm7srdkceEJK2VAmoUehfKHzDYhtCkPnZyElYwyeZAK7i6QY8u3WqGVIeGiObjZbhB2Ppq9wwSgfbaz5bUpKPwi6%2F3HRzV60gTURhO%2BOJOrxiuTjF6SKm586HQQizeGKWHlOiJghgO22gaqDlowHDMWuCjkPyk%2Fac1LTXNPFnUlQnbMwnvt7iXSRq6BrpZ7hlxxKZrjLT%2Bb35k4BExmE4XnXS%2BeWiSwNmz74xYtGwBzBjDYJL5KQPJBf%2FmmUqRgCV4xex7f8qtp34F4nLcXC0pRxggkSBBSxm214ubh9j7JZYz5QY8KuGDC9pn%2FeNeqFHaS4B%2FKtkNKzU6YyFmQdiXgFMpK22TpKvDQbeX5%2Bazx2lCqBuIR2MSg8xaVxfVOm14tu0WrqIY8luKV9Vpl23LWs713xhg80XwjkUb1nCOu57Lu0hOODrq1lr21CmJWnU7pttLa6fgT2Sineu%2BwkXeTQuVVBfYOw%2BQgyu6yX7hSkskKFMJPSSvSDgcx%2B0z7ze%2F6wwDfc2j94FtriCv77t7RIN1UQYi4%2FWT%2BH1UtqoHEjwf%2B4WUV4sGnzYnWVVNS9D%2FDuhfIcxMtX%2FeC6GY2xl3DaoInj4Dpn%2F%2B%2B%2BDMJy29J0GOqgBLYwZ%2BS6LeU8LGjYX9awM1lZICDgrQ0hlOV350Z6dYGfgRriIVxT3a1tcWbIoa3i2xkJhWKoJlEjgplRBSMEKhYaLbb9OQjKayNjAfDHGNDGr3%2FeGWuhg7SXAXHa1fs1%2BDqeErCylLFgS3TzFH2D7uTNCiSa6z2QS47PQ5lCYhjWqx9odsrCOmAKTrg23disfNZOaHKnlZaug2Yn7zDgbNneWs%2FKjX5GX&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230110T083848Z&X-Amz-SignedHeaders=content-md5%3Bhost%3Bx-amz-server-side-encryption&X-Amz-Expires=3600&X-Amz-Credential=ASIAXFYJLCYVPNLGNNGA%2F20230110%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=00adb6369887346dafc2fdce630f1527ab9482fb2307c921d2850b0d09c0aace",
        "expiry": "2026-01-10T09:`38:48`.910Z"
    },
    "status": {
        "code": "uploading"
    },
    "createdAt": "2026-01-10T08:`38:48`.910Z",
    "modifiedAt": "2026-01-10T08:`38:48`.910Z"
}

```