API documentation

Everything you need to integrate trusqo into your application.

Authentication

All API requests require an API key passed in the X-API-Key header. You can create and manage API keys from the dashboard.

curl https://app.trusqo.com/api/verify \
  -H "X-API-Key: YOUR_API_KEY"

Requests without a valid API key will receive a 401 Unauthorized response.

Submit a verification

POST /api/verify

Submit a document for proof of address verification. The request must be sent as multipart/form-data.

Required fields

Field	Type	Description
`name`	string	Full name of the person to verify
`address`	string	Address to verify against
`files`	file(s)	One or more document files (PDF, JPG, PNG)

Optional fields

Field	Type	Default	Description
`postcode`	string	—	Postcode to verify separately
`acceptedDocTypes`	JSON array	All types	Restrict accepted document types
`acceptedDateFrom`	YYYY-MM-DD	From settings	Earliest acceptable issue date
`acceptedDateTo`	YYYY-MM-DD	From settings	Latest acceptable issue date
`nameMatchThreshold`	float (0–1)	0.8	Minimum name match score to pass
`addressMatchThreshold`	float (0–1)	0.8	Minimum address match score to pass

Example request

curl -X POST https://app.trusqo.com/api/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "name=John Doe" \
  -F "address=123 Main Street, London SW1A 1AA" \
  -F "postcode=SW1A 1AA" \
  -F 'acceptedDocTypes=["utility-bill","bank-statement"]' \
  -F "acceptedDateFrom=2025-08-01" \
  -F "acceptedDateTo=2026-02-21" \
  -F "nameMatchThreshold=0.8" \
  -F "addressMatchThreshold=0.8" \
  -F "files=@utility-bill.pdf"

Response

Returns 202 Accepted with a request ID. The verification is processed asynchronously.

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Get verification result

GET /api/verify/{id}

Retrieve the result of a verification request by its ID. Poll this endpoint until status changes from pending/processing.

Response fields

Field	Type	Description
`id`	string	Request ID
`status`	string	`pending`, `processing`, `approved`, `declined`, or `needs_review`
`createdAt`	ISO 8601	Timestamp of submission
`nameMatchScore`	float \| null	Name similarity score (0–1)
`nameMatchResult`	string \| null	`pass` or `fail`
`addressMatchScore`	float \| null	Address similarity score (0–1)
`addressMatchResult`	string \| null	`pass` or `fail`
`postcodeMatchScore`	float \| null	Postcode match score
`postcodeMatchResult`	string \| null	`pass` or `fail`
`extractedDocType`	string \| null	Detected document type
`docTypeResult`	string \| null	`pass` or `fail`
`extractedDateOfIssue`	string \| null	Detected issue date
`dateResult`	string \| null	`pass` or `fail`
`extractedName`	string \| null	Best-match extracted name
`extractedAddress`	string \| null	Best-match extracted address
`errorMessage`	string \| null	Error details if processing failed

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "approved",
  "createdAt": "2026-02-21T14:30:00.000Z",

  "providedName": "John Doe",
  "extractedName": "John A. Doe",
  "nameMatchScore": 0.92,
  "nameMatchThreshold": 0.8,
  "nameMatchResult": "pass",

  "providedAddress": "123 Main Street, London SW1A 1AA",
  "extractedAddress": "123 Main St, London SW1A 1AA",
  "addressMatchScore": 0.95,
  "addressMatchThreshold": 0.8,
  "addressMatchResult": "pass",

  "providedPostcode": "SW1A 1AA",
  "extractedPostcode": "SW1A 1AA",
  "postcodeMatchScore": 1.0,
  "postcodeMatchResult": "pass",

  "extractedDocType": "utility-bill",
  "acceptedDocTypes": ["utility-bill", "bank-statement"],
  "docTypeResult": "pass",

  "extractedDateOfIssue": "2026-01-15",
  "acceptedDateFrom": "2025-08-01",
  "acceptedDateTo": "2026-02-21",
  "dateResult": "pass",

  "errorMessage": null
}

Accepted document types

Use these values in the acceptedDocTypes field to restrict which documents are accepted:

Value	Description
`utility-bill`	Gas, electricity, water, or internet bills
`bank-statement`	Bank or building society statements
`government-letter`	Letters from government agencies (tax, benefits, etc.)

Webhooks

Configure webhook URLs in the dashboard to receive real-time notifications when verification results are ready. Webhooks are sent as POST requests with a JSON payload containing the full verification result.

Each webhook includes an X-Webhook-Secret header with the secret you configured, so you can verify authenticity.

Error responses

All errors follow this format:

{
  "error": "Description of the error"
}

Status	Meaning
`400`	Missing or invalid required fields
`401`	Missing or invalid API key
`404`	Verification request not found
`500`	Internal server error