---
title: "Schema: Batches"
description: What is a batch and do I need to know about them? Batch attributes, optional attributes (extra_fields), relationships and example API calls
---
[Skip to content](https://support.parashift.io/schema-batches#main-content)
[Contact us](https://support.parashift.io/kb-tickets/new?hsLang=en) [Customer support portal](https://support.parashift.io/tickets-view?hsLang=en)
[](https://support.parashift.io/?hsLang=en)
Open main navigation
Close main navigation
- [Contact us](https://support.parashift.io/kb-tickets/new)
- [Customer support portal](https://support.parashift.io/tickets-view)
How can we help you?
- There are no suggestions because the search field is empty.
1. [Support Center](https://support.parashift.io/?hsLang=en)
2. [API Documentation](https://support.parashift.io/api-documentation?hsLang=en)
3. [Technical API Documentation](https://support.parashift.io/api-documentation?hsLang=en#technical-api-documentation)
# Schema: Batches
## What is a batch and do I need to know about them? Batch attributes, optional attributes (extra\_fields), relationships and example API calls
### Introduction
The Parashift Platform is capable of separating incoming documents (e.g. 20-page pdf) into multiple smaller documents (e.g. 5 documents with 4 pages each). A "batch" is used to keep the relation between the originally uploaded file(s) and the documents created from that file.
One single document has always one batch, while one batch consists of at least one but often multiple documents.
Depending on your use case you either heavily rely on batches (you use separation) or you don't need them at all (every uploaded document is already separated correctly).
### Attributes
| **Name** | **Type** | **Writable** | **Details** | **links** |
| --- | --- | --- | --- | --- |
| name | string | on create | | |
| status | string | no | Allowed values: pending, in\_progress, done, failed | [Workflow: Batches](https://support.parashift.io/workflow-batches?hsLang=en) |
| upload\_configuration | string | on create | | |
| validation\_required | boolean | no | | |
| created\_at | datetime | no | | |
| updated\_at | datetime | no | | |
### Optional Attributes (extra\_fields)
none
### Relationships (include)
officially none
There is no public relationship in the API between batch and document. One common use case is however to get all documents belonging to one batch.
If you want to do this just query for documents and filter on the batch id, e.g.
GET /documents/?filter\[batch\_id\]=123456
### Example API Calls
#### Show single batch
```
GET /Batches/123456
```
response
```
{ "data": { "id": "123456", "type": "batches", "attributes": { "created_at": "2022-03-10T09:38:53.532823Z", "name": "Batch-manual.pdf", "status": "in_progress", "tenant_id": "543", "updated_at": "2022-03-10T09:39:09.841364Z", "upload_configuration": "client", "validation_required": true } }, "meta": {}}
```
#### List batches
```
GET /Batches/
```
response
```
{ "data": [ { "id": "111111", "type": "batches", "attributes": { "created_at": "2020-11-25T19:24:01.175038Z", "name": null, "status": "in_progress", "tenant_id": "543", "updated_at": "2022-03-04T14:10:00.661514Z", "upload_configuration": "client", "validation_required": true } }, { "id": "222222", "type": "batches", "attributes": { "created_at": "2020-12-08T09:55:03.084905Z", "name": null, "status": "done", "tenant_id": "543", "updated_at": "2021-01-07T17:07:40.399357Z", "upload_configuration": "client", "validation_required": true } } ], "meta": {}}
```
Recommended Reading
I strongly recommend the following articles, going into detail about how a batch is related to documents, pages and especially input\_files.
- [Relationships & Structure of Batches, Documents, Pages and Files](https://support.parashift.io/structure-relationsships-of-batches-documents-pages-and-files?hsLang=en)
Also, check out our Postman API Documentation
- [API Documentation](https://docs.parashift.io/)
- [Getting Started](https://support.parashift.io/getting-started?hsLang=en)
- [User Guides](https://support.parashift.io/user-guides?hsLang=en#main-content)
- [General](https://support.parashift.io/user-guides?hsLang=en#general)
- [Validation](https://support.parashift.io/user-guides?hsLang=en#validation)
- [Platform Workshops](https://support.parashift.io/user-guides?hsLang=en#platform-workshops)
- [Configuration Guides](https://support.parashift.io/configuration-guides?hsLang=en#main-content)
- [Document Type & Fields](https://support.parashift.io/configuration-guides?hsLang=en#document-type-fields)
- [Automation](https://support.parashift.io/configuration-guides?hsLang=en#automation)
- [Tenant (User management)](https://support.parashift.io/configuration-guides?hsLang=en#tenant-user-management)
- [Workflow (Upload Configuration, Separation, Classification)](https://support.parashift.io/configuration-guides?hsLang=en#workflow-upload-configuration-separation-classification)
- [Release Notes](https://support.parashift.io/release-notes?hsLang=en)
- [API Documentation](https://support.parashift.io/api-documentation?hsLang=en#main-content)
- [Platform API Configuration](https://support.parashift.io/api-documentation?hsLang=en#platform-api-configuration)
- [Technical API Documentation](https://support.parashift.io/api-documentation?hsLang=en#technical-api-documentation)
- [Professional Services](https://support.parashift.io/professional-services?hsLang=en#main-content)
- [Project-based Service Packages](https://support.parashift.io/professional-services?hsLang=en#project-based-service-packages)
- [Subscription-based Service Packages](https://support.parashift.io/professional-services?hsLang=en#subscription-based-service-packages)
[](https://support.parashift.io/?hsLang=en)
[Platform Live Status](https://status.parashift.io/) | [API Documentation](https://docs.parashift.io/)
[mailto:support@parashift.io](mailto:support@parashift.io)
Copyright © 2025, Parashift AG