Document Submit Batch

Upload up to 25 documents in a single request. Each item targets a user identified by their external reference.

Endpoint

POST /v1/documents:submitBatch

Authentication

Required Scopes: pearsana-partner/partners.documents:write and pearsana-partner/partners.externalRefs:read

Optional Scope: pearsana-partner/partners.verifications:write — required if any item uses a verificationIntent other than store_only.

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
X-API-Version: 2026-01-30

Request Body

{
	"items": [
		{
			"itemId": "item-001",
			"externalReference": {
				"namespace": "SIS",
				"externalId": "STU-2024-001"
			},
			"documentType": "OFFICIAL_TRANSCRIPT",
			"file": "JVBERi0xLjQK...",
			"filename": "transcript-jane-smith.pdf",
			"verificationIntent": "store_only"
		},
		{
			"itemId": "item-002",
			"externalReference": {
				"namespace": "SIS",
				"externalId": "STU-2024-002"
			},
			"documentType": "DEGREE_CERTIFICATE",
			"file": "JVBERi0xLjQK...",
			"filename": "degree-john-doe.pdf",
			"verificationIntent": "attest",
			"attestationReferenceId": "ATT-2024-001"
		}
	]
}

Request Parameters

Top Level

Field	Type	Required	Description
items	array	Yes	Array of batch items. Maximum 25 items per request.

Batch Item

Each item in the items array accepts the same fields as Document Submit, plus the following:

Field	Type	Required	Description
itemId	string	Yes	A client-provided identifier for this item. Must be unique within the batch. Used to correlate results.
metadata	object	No	Arbitrary key-value metadata attached to this item
partnerReferenceId	string	No	An optional partner-side reference identifier
externalReference	object	Yes	Identifies the user (see Document Submit)
documentType	string	Yes	See Document Types
file	string	Yes	Base64-encoded file content
filename	string	No	Original filename
verificationIntent	string	No	Default: store_only. See Verification Intent
attestationReferenceId	string	No	Required when verificationIntent is attest
verificationMetadata	object	No	Arbitrary metadata attached to the verification record

Response

The batch endpoint uses HTTP status codes to indicate the overall outcome:

Status Code	Meaning
201 Created	Every item succeeded
207 Multi-Status	Some items succeeded, some failed
400 Bad Request	Every item failed, or the request itself is invalid

Response Body

{
	"results": [
		{
			"itemId": "item-001",
			"status": "created",
			"document": {
				"documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
				"documentFingerprintId": "sha256:e3b0c44298fc1c...",
				"status": "received",
				"createdAt": "2026-01-30T12:00:00.000Z"
			}
		},
		{
			"itemId": "item-002",
			"status": "failed",
			"error": {
				"code": "NOT_FOUND",
				"message": "User not found for external reference SIS/STU-2024-002"
			}
		}
	]
}

Result Item Fields

Field	Type	Description
itemId	string	The itemId from the request, for correlation
status	string	created or failed
document	object	Present when status is created. Same shape as the single submit response.
verification	object	Present when status is created and verificationIntent is not store_only. Same shape as the single submit response.
error	object	Present when status is failed. Contains code and message.

Error Responses

400 — Request-Level Validation Error

Returned when the request structure itself is invalid (e.g. missing items array, exceeding the 25-item limit, or duplicate itemId values).

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Batch size exceeds maximum of 25 items",
		"requestId": "abc-123-def"
	}
}

400 — All Items Failed

When every individual item fails, the response is 400 with all failures in the results array.

{
	"results": [
		{
			"itemId": "item-001",
			"status": "failed",
			"error": {
				"code": "VALIDATION_ERROR",
				"message": "file is required (base64 encoded content)"
			}
		}
	]
}

401 / 403

See Error Format for the standard error envelope.

Example Request

curl -X POST https://sandbox.api.pearsana.com/v1/documents:submitBatch \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-01-30" \
  -d '{
    "items": [
      {
        "itemId": "item-001",
        "externalReference": {
          "namespace": "SIS",
          "externalId": "STU-2024-001"
        },
        "documentType": "OFFICIAL_TRANSCRIPT",
        "file": "JVBERi0xLjQK...",
        "filename": "transcript.pdf",
        "verificationIntent": "store_only"
      },
      {
        "itemId": "item-002",
        "externalReference": {
          "namespace": "SIS",
          "externalId": "STU-2024-002"
        },
        "documentType": "DEGREE_CERTIFICATE",
        "file": "JVBERi0xLjQK...",
        "verificationIntent": "issue"
      }
    ]
  }'

Batch Processing Notes

Partial success is expected

With status 207, some items succeeded and some failed. Always check the status field on each result item rather than relying solely on the HTTP status code.

Item ID uniqueness

Every itemId in a batch must be unique. Duplicate itemId values will cause a validation error for the entire request.

Related Endpoints

• Document Submit — submit a single document