Document Submit

Upload a single document for a user identified by their external reference.

Endpoint

POST /v1/documents:submit

Authentication

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

Optional Scope: pearsana-partner/partners.verifications:write — required if verificationIntent is anything other than store_only.

Headers

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

Request Body

{
	"externalReference": {
		"namespace": "SIS",
		"externalId": "STU-2024-001"
	},
	"documentType": "OFFICIAL_TRANSCRIPT",
	"file": "JVBERi0xLjQK...",
	"filename": "transcript-jane-smith.pdf",
	"verificationIntent": "store_only"
}

Request Parameters

Field	Type	Required	Description
externalReference	object	Yes	Identifies the user (see below)
documentType	string	Yes	Document type (see Document Types)
file	string	Yes	Base64-encoded file content
filename	string	No	Original filename — used for MIME type detection. If omitted, MIME type defaults to application/octet-stream
verificationIntent	string	No	What to do with the document after upload (default: store_only). See Verification Intent
attestationReferenceId	string	No	Only valid when verificationIntent is attest
verificationMetadata	object	No	Arbitrary metadata attached to the verification record

External Reference Object

Field	Type	Required	Description
namespace	string	Yes	System namespace (e.g. "SIS", "LMS")
externalId	string	Yes	External system identifier for the user

The user must already exist in Pearsana and have this external reference linked. If no matching user is found, the API returns 404.

Document Types

Value	Category
OFFICIAL_TRANSCRIPT	academic
ACADEMIC_TRANSCRIPT	academic
DEGREE_CERTIFICATE	academic
DIPLOMA	academic
ENROLLMENT_VERIFICATION	academic
COURSE_COMPLETION	academic
AWARD_CERTIFICATE	awards
HONOR_ROLL	awards
SPORTS_CERTIFICATE	sports
ATHLETIC_RECORD	sports

Any other value is accepted and categorised as personal.

Verification Intent

Controls what happens to the document after it is stored.

Value	Behaviour
store_only	(default) Document is uploaded to the user's Wallet. No verification is created.
request	Document is uploaded and a verification request is created with status received.
attest	Document is uploaded and a verification is created with status approved (attested by the partner). Requires attestationReferenceId.
issue	Document is uploaded and a verification is created with status approved (issued by the partner).

Verification scope

If verificationIntent is anything other than store_only, your App Client must also have the pearsana-partner/partners.verifications:write scope.

Response

Success Response

Status Code: 201 Created

{
	"document": {
		"documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"documentFingerprintId": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
		"status": "received",
		"createdAt": "2026-01-30T12:00:00.000Z"
	}
}

When a verification is created (i.e. verificationIntent is not store_only):

{
	"document": {
		"documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"documentFingerprintId": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
		"status": "verified",
		"createdAt": "2026-01-30T12:00:00.000Z"
	},
	"verification": {
		"verificationId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
		"verificationType": "attested",
		"status": "approved",
		"createdAt": "2026-01-30T12:00:00.000Z",
		"attestationReferenceId": "ATT-2024-001"
	}
}

Response Fields — Document

Field	Type	Description
documentId	string	Unique document identifier
documentFingerprintId	string	SHA-256 hash of the file content, prefixed with sha256:
status	string	received (store only / request) or verified (attest / issue)
createdAt	string	ISO 8601 timestamp

Response Fields — Verification (when present)

Field	Type	Description
verificationId	string	Unique verification identifier
verificationType	string	requested, attested, or issued
status	string	received (request) or approved (attest / issue)
createdAt	string	ISO 8601 timestamp
attestationReferenceId	string	Present only for attest intent

Error Responses

400 Validation Error

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Validation failed",
		"details": {
			"errors": ["externalReference.namespace is required", "file is required (base64 encoded content)"]
		},
		"requestId": "abc-123-def"
	}
}

404 User Not Found

{
	"error": {
		"code": "NOT_FOUND",
		"message": "User not found for external reference SIS/STU-2024-001",
		"requestId": "abc-123-def"
	}
}

401 / 403

See Error Format for the standard error envelope.

Example Request

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

Related Endpoints

• Document Submit Batch — submit up to 25 documents in a single request