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, WEBP)

Optional fields

Field	Type	Default	Description
`postcode`	string	—	Postcode to verify separately
`acceptedDocTypes`	JSON array	From settings	Restrict accepted document types
`acceptedDateFrom`	YYYY-MM-DD	From settings	Earliest acceptable issue date
`acceptedDateTo`	YYYY-MM-DD	From settings	Latest acceptable issue date
`nameMatchEnabled`	boolean	true	Enable name matching
`nameMatchThreshold`	float (0–1)	0.8	Minimum name match score to pass
`addressMatchEnabled`	boolean	true	Enable address matching
`addressMatchThreshold`	float (0–1)	0.8	Minimum address match score to pass
`postcodeMatchEnabled`	boolean	false	Enable postcode matching
`postcodeMatchThreshold`	float (0–1)	0.7	Minimum postcode 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 "nameMatchEnabled=true" \
  -F "nameMatchThreshold=0.8" \
  -F "addressMatchEnabled=true" \
  -F "addressMatchThreshold=0.8" \
  -F "postcodeMatchEnabled=true" \
  -F "postcodeMatchThreshold=0.7" \
  -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`, `needs_review`, or `errored`
`createdAt`	ISO 8601	Timestamp of submission
`providedName`	string	Name submitted for verification
`extractedName`	string \| null	Best-match extracted name
`extractedNames`	array	All names found in the document
`nameMatchScore`	float \| null	Name similarity score (0–1)
`nameMatchThreshold`	float	Threshold used for name matching
`nameMatchResult`	string \| null	`pass` or `fail`
`nameMatchNotes`	string \| null	Additional notes on the name match
`providedAddress`	string	Address submitted for verification
`extractedAddress`	string \| null	Best-match extracted address
`extractedAddresses`	array	All addresses found in the document
`addressMatchScore`	float \| null	Address similarity score (0–1)
`addressMatchThreshold`	float	Threshold used for address matching
`addressMatchResult`	string \| null	`pass` or `fail`
`addressMatchNotes`	string \| null	Additional notes on the address match
`providedPostcode`	string \| null	Postcode submitted for verification
`extractedPostcode`	string \| null	Postcode from the best-match address
`postcodeMatchScore`	float \| null	Postcode match score (0–1)
`postcodeMatchResult`	string \| null	`pass` or `fail`
`postcodeMatchNotes`	string \| null	Additional notes on the postcode match
`extractedDocType`	string \| null	Detected document type
`acceptedDocTypes`	array	Document types that were accepted
`docTypeResult`	string \| null	`pass` or `fail`
`extractedDateOfIssue`	string \| null	Best-match detected issue date
`extractedDates`	array	All dates found in the document
`acceptedDateFrom`	string \| null	Earliest accepted date used
`acceptedDateTo`	string \| null	Latest accepted date used
`dateResult`	string \| null	`pass` or `fail`
`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",
  "extractedNames": ["John A. Doe", "J. Doe"],
  "nameMatchScore": 0.92,
  "nameMatchThreshold": 0.8,
  "nameMatchResult": "pass",
  "nameMatchNotes": null,

  "providedAddress": "123 Main Street, London SW1A 1AA",
  "extractedAddress": "123 Main St, London SW1A 1AA",
  "extractedAddresses": [
    { "address": "123 Main St, London SW1A 1AA", "postcode": "SW1A 1AA" }
  ],
  "addressMatchScore": 0.95,
  "addressMatchThreshold": 0.8,
  "addressMatchResult": "pass",
  "addressMatchNotes": null,

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

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

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

  "errorMessage": null
}

Download verification report

GET /api/verify/{id}/report

Download a PDF report summarizing the verification result. The report includes match scores, extracted data, audit trail, and comments.

The verification must be completed before a report can be generated. Requests for pending or processing verifications will return 404.

Example request

curl https://app.trusqo.com/api/verify/a1b2c3d4-e5f6-7890-abcd-ef1234567890/report \
  -H "X-API-Key: YOUR_API_KEY" \
  -o report.pdf

Response

Returns 200 OK with Content-Type: application/pdf. The response body is the binary PDF file.

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.)
`medical-or-pharmacy-bill`	Healthcare providers, pharmacies
`post-office-letter`	Postal services, courier companies
`life-insurance`	Insurance companies (life insurance only)

Webhooks

Configure webhook URLs in the dashboard to receive real-time notifications when verification status changes. Webhooks are sent as POST requests with a JSON payload.

Event types

Event	Description
`verification.processing`	Verification has started processing
`verification.completed`	Verification finished (approved, declined, or needs review)
`verification.failed`	Verification encountered an error

Headers

Each webhook request includes these headers:

Header	Description
`X-Signature-256`	HMAC-SHA256 signature of the payload, formatted as `sha256=<hex>`
`X-Webhook-Event`	The event type (e.g. `verification.completed`)

Verify authenticity by computing HMAC-SHA256(payload, your_webhook_secret) and comparing it to the X-Signature-256 header value.

Payload

{
  "event": "verification.completed",
  "timestamp": "2026-02-21T14:30:05.000Z",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "approved",
    "providedName": "John Doe",
    "providedAddress": "123 Main Street, London SW1A 1AA",
    "extractedName": "John A. Doe",
    "extractedAddress": "123 Main St, London SW1A 1AA",
    "nameMatchScore": 0.92,
    "nameMatchResult": "pass",
    "addressMatchScore": 0.95,
    "addressMatchResult": "pass",
    "extractedDocType": "utility-bill",
    "errorMessage": null
  }
}

MCP server

Use trusqo directly from AI assistants like Claude, Cursor, or any MCP-compatible client. The MCP server exposes three tools: submit a verification, check the result, and download the PDF report.

Install

npm install -g trusqo-mcp

Or run without installing using npx -y trusqo-mcp.

Configuration

Add to your AI assistant's MCP config with your API key:

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trusqo": {
      "command": "npx",
      "args": ["-y", "trusqo-mcp"],
      "env": {
        "TRUSQO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code

claude mcp add trusqo -- npx -y trusqo-mcp

Set the TRUSQO_API_KEY environment variable before running Claude Code.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "trusqo": {
      "command": "npx",
      "args": ["-y", "trusqo-mcp"],
      "env": {
        "TRUSQO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Available tools

Tool	Description
`verify_document`	Submit a document for verification. Accepts local file paths, person's name, and address. Returns a request ID.
`get_verification_result`	Check the status and results of a verification request. Poll until status is no longer `pending` or `processing`.
`download_verification_report`	Download the PDF verification report and save it locally.

Environment variables

Variable	Required	Default	Description
`TRUSQO_API_KEY`	Yes	—	Your API key (starts with `poa_`)
`TRUSQO_BASE_URL`	No	https://app.trusqo.com	API base URL

View the package on npm.

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
`402`	Usage limit exceeded or no active subscription
`404`	Verification request not found
`500`	Internal server error