Pearsana Partner API

The Pearsana Partner API allows your systems to programmatically create users, send invitations, and submit documents into Pearsana on behalf of your organisation.

Trusted Partners Only

Access to the Pearsana Partner API is restricted to trusted partner organisations. If your organisation is interested in becoming a trusted partner, please reach out to us at support@pearsana.com.

Base URLs

Environment	API	Auth
Sandbox	https://sandbox.api.pearsana.com	https://sandbox.auth.pearsana.com
Production	https://api.pearsana.com	https://auth.pearsana.com

All code examples in these docs use the Sandbox URLs. Replace with the Production URLs when you are ready to go live.

Endpoints

Method	Path	Description	Doc
GET	/health	Service health check (no auth)	Health Check
GET	/ping	Auth connectivity test	Ping
POST	/v1/users	Create a user	Create User
POST	/v1/invitations	Create an invitation	Create Invitation
POST	/v1/documents:submit	Submit a single document	Document Submit
POST	/v1/documents:submitBatch	Submit up to 25 documents	Document Submit Batch

Authentication

All endpoints except /health require an OAuth 2.0 access token obtained via the Client Credentials grant.

curl https://sandbox.api.pearsana.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-01-30"

See Authentication for the full flow, including how to request a token.

API Versioning

Include the X-API-Version header with a date-based version string on every request:

X-API-Version: 2026-01-30

The API returns these headers on every response:

Response Header	Description
X-API-Version	The version applied to this request
X-API-Version-Latest	The newest available version
X-API-Version-Supported	The oldest version still supported

If you send an unsupported version, the API returns 410 Gone with details of the oldest supported version.

Request ID

Every response includes an X-Request-Id header. You can also send your own X-Request-Id on a request — the API will use it instead of generating one. This value also appears inside error responses, making it useful for support tickets.

Error Format

All errors follow the same envelope structure:

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Validation failed",
		"details": {
			"errors": ["identity.email is required"]
		},
		"requestId": "abc-123-def"
	}
}

Field	Type	Always present	Description
error.code	string	Yes	Machine-readable error code (see table below)
error.message	string	Yes	Human-readable description
error.details	object	No	Additional context (varies by error)
error.requestId	string	Yes	Unique request identifier

Error Codes

Code	HTTP Status	Meaning
VALIDATION_ERROR	400	Request body failed validation
INVALID_API_VERSION	400	X-API-Version header is missing or invalid
UNAUTHORIZED	401	Missing or invalid access token
FORBIDDEN	403	Valid token but access denied
INSUFFICIENT_SCOPE	403	Token does not have the required scopes
NOT_FOUND	404	Resource or user not found
CONFLICT	409	Duplicate email or resource
EXTERNAL_REF_CONFLICT	409	External reference already linked to another user
UNSUPPORTED_API_VERSION	410	API version is no longer supported
TOO_MANY_REQUESTS	429	Rate limit exceeded
INTERNAL_SERVER_ERROR	500	Unexpected server error

Getting Started

1. Create an App Client in the Pearsana organisation portal to get your Client ID and Client Secret.
2. Request an access token using the Client Credentials grant.
3. Start calling endpoints.