Skip to main content
POST
/
extractions
/
templates
/
{templateId}
/
sessions
/
batch
Batch Create Sessions
curl --request POST \
  --url https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "files": [
    "tmp/abc123-invoice.pdf",
    "tmp/def456-invoice.pdf"
  ],
  "settings": {
    "auto_extract": false
  }
}
'
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Pending...",
    "created_at": "2023-11-07T05:31:56Z"
  }
]

​
Authentication & Scope

Requires the sessions-write ability.

​
Overview

This endpoint creates one session per uploaded file, with each session containing the corresponding document. This is the most efficient way to process multiple documents.
Enable auto_extract to automatically start extraction after document parsing completes. This eliminates the need to call the execute endpoint separately.

​
Request

POST /extractions/templates/550e8400-e29b-41d4-a716-446655440000/sessions/batch HTTP/1.1
Host: api.raydocs.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "files": [
    "tmp/abc123-invoice1.pdf",
    "tmp/def456-invoice2.pdf",
    "tmp/ghi789-invoice3.pdf"
  ],
  "settings": {
    "auto_extract": true
  }
}

​
Path Parameters

ParameterTypeRequiredDescription
templateIduuidYesThe template ID to use for extraction

​
Body Parameters

ParameterTypeRequiredDescription
filesarrayYesArray of file keys from signed URL uploads (max 50)
settingsobjectNoSession settings
settings.auto_extractbooleanNoWhen true, extraction starts automatically after document parsing (default: false)
File keys are obtained from the signed URL upload process. Each file creates a separate session.

​
Response

201 Created – Array of created sessions. 
[
  {
    "id": "770e8400-e29b-41d4-a716-446655440001",
    "name": "Pending...",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Pending...",
    "created_at": "2024-01-15T10:30:01Z"
  },
  {
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "name": "Pending...",
    "created_at": "2024-01-15T10:30:02Z"
  }
]
Session names initially show “Pending…” and are automatically updated to the document filename once processing begins.

​
Auto-Extract Workflow

When auto_extract: true:
  1. Sessions are created with uploaded documents
  2. Documents are automatically parsed into searchable chunks
  3. Once parsing completes, extraction starts automatically
  4. Results appear in the session’s results endpoint
With auto-extract enabled, you don’t need to call the Batch Execute endpoint. Doing so would create duplicate extraction jobs.

​
Example: Complete Workflow

1

Upload files and get keys

Use signed URLs to upload your documents first.
2

Batch create with auto-extract

curl -X POST "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["tmp/file1.pdf", "tmp/file2.pdf"],
    "settings": { "auto_extract": true }
  }'
3

Poll for results

Check each session’s results endpoint until status is completed.
curl "https://api.raydocs.com/extractions/sessions/{sessionId}/results" \
  -H "Authorization: Bearer <token>"

​
Error Responses

StatusDescription
403Token lacks sessions-write ability
404Template not found
422Validation error (invalid file keys, exceeds 50 file limit)

Authorizations

​
Authorization
string
header
required

Personal Access Token

Path Parameters

​
templateId
string<uuid>
required

Body

application/json
​
files
string[]
required

Array of file keys from signed URL uploads

Maximum array length: 50
Example:
[
  "tmp/abc123-invoice.pdf",
  "tmp/def456-invoice.pdf"
]
​
settings
object

Response

Sessions created

​
id
string<uuid>
​
name
string
Example:

"Pending..."

​
created_at
string<date-time>