---
updatedAt: 2025-09-15T22:19:25.000Z
agentTools:
  projectIndex: https://apidocs.ceretax.net/llms.txt
---

# About the Batch API

The CereTax Batch API supports uploading a batch file of transactions for processing. Creating a transaction batch using the CereTax API involves the following steps:

1. Create a batch record and generate a tokenized url for uploading your batch file
2. Upload your batch file to the CereTax-generated url
3. Confirm your batch file completed processing and download results

## Example

### 1. Create a batch record and generate a tokenized url for uploading your batch file

In this step, you will call the \[Create or retrieve a batch]\(Create or retrieve a batch) endpoint, which will create a record for your batch in the CereTax system, assign it a unique id, and generate a url for you to upload your batch file to.

Note: templateName is optional

> 📘 The name of the file you upload must match the file name stated in this step.

```curl Create a batch request example
curl --location 'https://batch.cert.ceretax.net/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
  "command": "upload",
  "fileName": "August2023_Batch_Upload.xlsx",
  "batchName": "August 2023 Batch Upload",
  "requestType": "telco",
  "calculationType: "S",
  "contentMonth": "07",
  "contentYear": "2025",
  "profileId": "telco",
  "businessType": "01",
  "customerType": "02",
  "taxSitusRule": "T",
  "sellerType": "01",
  "templateName": ""
}
'
```

In the response below, you can see that CereTax was able to create a record for the batch and respond back with a tokenized url that can be used to upload the batch file in the next step. A batchId is also provided in the response, which can be used to retrieve the status of the batch after your batch file is uploaded.

> 📘 Batch upload url expires after 15 mins
>
> The url returned in this request for uploading your batch file will be valid for 15 mins. After 15 mins, a new url will need to be generated by creating a new batch record.

```json Create a batch response example
{
  "success": true,
  "url": "https://...",
  "batchId": "29iNnnfesNoBTO8o0wQDZpna5Vo",
  "status": "",
  "error": ""
}
```

### 2. Upload your batch file to the CereTax-generated url

In this step, you will perform a PUT request against the url generated in Step 1. In this example, an excel file is being upload.  Content-Type should be set to one of the following supported types:

* application/json
* application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
* text/csv

> 📘 The name of the file you upload must match the file name stated in Step 1

```curl Upload batch file request example
curl --location --request PUT '{url from step 1}' \
--header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
--data '@[dir]/August2023_Batch_Upload.xlsx'
```

If the file is uploaded successfully, CereTax will respond back with a status code of 200.

### 3. Confirm your batch file completed processing and download results

After you successfully upload your batch file, you can call the [Create or retrieve a batch](https://apidocs.ceretax.net/reference/post-batch-create) endpoint again to retrieve the status of your batch. This time, provide the batchId and set the command to "status".

```json Retrieve a batch request example
curl --location 'https://batch.cert.ceretax.net' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
  "command": "status",
  "batchIds": ["29iNnnfesNoBTO8o0wQDZpna5Vo"]
}
'
```

In the response below, you can see that CereTax has finished processing the batch and set the status to "Batch Complete". The response also includes a url that can be used to download the results of your batch.

> 📘 Batch download url expires after 15 mins
>
> The url returned in this request for downloading your batch results will be valid for 15 mins. After 15 mins, a new url will need to be generated by making another batch status request.

```json Retrieve a batch response example
[
  {
    "batchId": "29iNnnfesNoBTO8o0wQDZpna5Vo",
    "batchName": " August 2023 Batch Upload",
    "status": "Batch Complete",
    "percentCompleted": 100,
    "percentFailed": 0,
    "downloadUrl": "https://..."
  }
]
```