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
  }
}
'

import requests

url = "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch"

payload = {
    "files": ["tmp/abc123-invoice.pdf", "tmp/def456-invoice.pdf"],
    "settings": { "auto_extract": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: ['tmp/abc123-invoice.pdf', 'tmp/def456-invoice.pdf'],
    settings: {auto_extract: false}
  })
};

fetch('https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'files' => [
        'tmp/abc123-invoice.pdf',
        'tmp/def456-invoice.pdf'
    ],
    'settings' => [
        'auto_extract' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch"

	payload := strings.NewReader("{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}"

response = http.request(request)
puts response.read_body

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Pending...",
    "created_at": "2023-11-07T05:31:56Z"
  }
]

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
  }
}
'

import requests

url = "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch"

payload = {
    "files": ["tmp/abc123-invoice.pdf", "tmp/def456-invoice.pdf"],
    "settings": { "auto_extract": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: ['tmp/abc123-invoice.pdf', 'tmp/def456-invoice.pdf'],
    settings: {auto_extract: false}
  })
};

fetch('https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'files' => [
        'tmp/abc123-invoice.pdf',
        'tmp/def456-invoice.pdf'
    ],
    'settings' => [
        'auto_extract' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch"

	payload := strings.NewReader("{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.raydocs.com/extractions/templates/{templateId}/sessions/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"files\": [\n    \"tmp/abc123-invoice.pdf\",\n    \"tmp/def456-invoice.pdf\"\n  ],\n  \"settings\": {\n    \"auto_extract\": false\n  }\n}"

response = http.request(request)
puts response.read_body

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

Parameter	Type	Required	Description
`templateId`	uuid	Yes	The template ID to use for extraction

Body Parameters

Parameter	Type	Required	Description
`files`	array	Yes	Array of file keys from signed URL uploads (max 50)
`settings`	object	No	Session settings
`settings.auto_extract`	boolean	No	When `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:

Sessions are created with uploaded documents
Documents are automatically parsed into searchable chunks
Once parsing completes, extraction starts automatically
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

Upload files and get keys

Use signed URLs to upload your documents first.

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 }
  }'

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

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

Authorizations

Authorization

string

header

required

Personal Access Token created from the Raydocs dashboard. Include in the Authorization header: Bearer <your_token> See API Keys for token creation and management.

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

Show child attributes

Response

Sessions created

string<uuid>

name

string

Example:

"Pending..."

created_at

string<date-time>

Overview

Cookbook

Workspaces

Workspace Users

Extraction Templates

Extraction Sessions

Batch Operations

Documents

Workflows

Results

Batch Create Sessions

Authentication & Scope

Overview

Request

Path Parameters

Body Parameters

Response

Auto-Extract Workflow

Example: Complete Workflow

Error Responses

Authorizations

Path Parameters

Body

Response

​Authentication & Scope

​Overview

​Request

​Path Parameters

​Body Parameters

​Response

​Auto-Extract Workflow

​Example: Complete Workflow

​Error Responses

Authorizations

Path Parameters

Body

Response

Authentication & Scope

Overview

Request

Path Parameters

Body Parameters

Response

Auto-Extract Workflow

Example: Complete Workflow

Error Responses