Pixl Cognitive Services (PCS)

Pixl Cognitive Services (PCS) is a set of RESTful APIs that read structured data out of photos or scans of identity documents. Send an image as a base64 / data-URI string and the response returns the fields extracted from it — no manual data entry required.

Each document type (and, where a document has two sides, each side) has its own endpoint, but they all share the same conventions:

Stateless REST

Every endpoint is a single POST call over HTTPS, request and response bodies are JSON.

Key-based auth

Requests are authenticated with a static key sent in the request header.

Base64 images

The document image is sent as a base64 string or a data URI — no file upload.

Authentication

Every PCS request must carry your API key in the key request header:

curl <access-url> \
  --header 'key: <your-api-key>'

:::note Base URL The base URL is issued per account during onboarding, e.g. https://sandbox. All paths below are relative to it and prefixed with /pcs. :::

Sending the image

The image field accepts either:

A raw base64 string, or
A data URI, e.g. data:image/png;base64,<BASE64_STRING>

Requests also take a recordId — a unique identifier of your choosing that is echoed back in the response so you can correlate it with your own records.

APIs covered in this guide

Document	Side	Endpoint
Passport	Front	`POST /pcs/passport/front`
Passport	Back	`POST /pcs/passport/back`
PAN Card	—	`POST /pcs/pan1`
Aadhaar Card	Front	`POST /pcs/aadhaar/front`
Aadhaar Card	Back	`POST /pcs/aadhaar/back`
Voter ID	Front	`POST /pcs/voter-id/front`
Voter ID	Back	`POST /pcs/voter-id/back`
Qatar ID	Front	`POST /pcs/QatarId/front`
Qatar ID	Back	`POST /pcs/QatarId/back`
Emirates ID	Front	`POST /pcs/emiratesId/front`
Emirates ID	Back	`POST /pcs/emiratesId/back`
Malaysian ID	—	`POST /pcs/MalaysianId`
Malaysian Driving Licence	—	`POST /pcs/MalaysianDL`
Mexican Voter ID	Front	`POST /pcs/MexicanVoterIdFront`
Mexican Voter ID	Back	`POST /pcs/MexicanVoterIdBack`
UAE Visa	—	`POST /pcs/UAEVisa`
US Insurance Card	—	`POST /pcs/UsInsuranceCard`
QR Code Reader	—	`POST /pcs/QR-Reader`

Error handling

All PCS endpoints share the same HTTP status conventions:

HTTP code	Meaning	When returned
`200 OK`	Success	The request succeeded — see the endpoint's own response shape for the data payload.
`401 Unauthorized`	Auth error	The `key` header is missing or invalid.
`422 Unprocessable Entity`	Validation error	The request body failed validation (missing field, malformed image, etc).
`500 Internal Server Error`	Server error	An unexpected error occurred while processing the document.

A 422 response follows the standard FastAPI validation-error shape:

{
  "detail": [
    {
      "loc": ["body", "image"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Field	Type	Description
`detail`	array	One entry per validation failure.
`detail[].loc`	array	Location of the offending field, e.g. `["body", "image"]`.
`detail[].msg`	string	Human-readable description of the failure.
`detail[].type`	string	Machine-readable error type.

Authentication​

Sending the image​

APIs covered in this guide​

Error handling​

Authentication

Sending the image

APIs covered in this guide

Error handling