API
Build on the Postal.id verification network.
RESTful API with real-time HMAC-signed webhooks. Query verified identities, verify evidence packs, and create verification cases programmatically.
Verification Queries
Three ways to query the global verification marketplace.
Identity Check
POST /api/v1/postal-id/lookup-bulk
Query up to 500 email addresses to check if they have been verified by any Postal.id tenant. Returns verification status, decaying confidence score, assurance level, and reverification date.
const response = await fetch(
'https://api.postal.id/v1/postal-id/lookup-bulk',
{
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
emails: ['jane@example.com', 'john@example.com']
}),
}
)
// Response
{
"results": [
{
"email": "jane@example.com",
"found": true,
"verified": true,
"verificationScore": 87,
"assuranceLevel": "Email+SMS+Postal",
"verifiedAt": "2026-03-15T10:30:00Z",
"reverificationDue": "2029-01-12T00:00:00Z"
}
],
"summary": { "total": 2, "found": 1, "notFound": 1 },
"usage": { "queriesUsed": 2, "queriesRemaining": 498 }
}Address Match
POST /api/v1/postal-id/lookup-address
Verify that a person was verified at a specific address. Matches both email AND address hash for compliance-grade certainty. Higher assurance than identity check alone.
const response = await fetch(
'https://api.postal.id/v1/postal-id/lookup-address',
{
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
entries: [{
email: 'jane@example.com',
line1: '12 Baker Street',
city: 'London',
postalCode: 'NW1 6XE',
countryCode: 'GB'
}]
}),
}
)
// Matches both identity AND address for certaintyHash Verification
POST /api/v1/evidence/verify-bulk
Verify evidence pack integrity using only the SHA-256 hash from the PDF footer. No personal data transmitted to Postal.id. Returns anonymised case confirmation.
const response = await fetch(
'https://api.postal.id/v1/evidence/verify-bulk',
{
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
hashes: [
'6ff534591a2b3c4d5e6f...'
]
}),
}
)
// No PII transmitted — GDPR-friendly verificationCase Management
Create and manage verification cases programmatically.
Create Case
POST /api/v1/cases
Submit subject name, email, address, and verification bundle. Postal letters dispatched automatically. Digital OTPs sent instantly.
Get Case Status
GET /api/v1/cases/:id
Poll case status, layer progress, risk signals, and verification attempts. Full case lifecycle visibility.
Webhooks
HMAC-SHA256 signed
Real-time event notifications: case created, postal dispatched, OTP verified, case complete. 25+ event types with retry logic.
Authentication
Simple API key authentication.
How it works
- 1Generate API keys from your dashboard under Settings
- 2Include your key as a Bearer token in the Authorization header
- 3Use pk_test_ keys for sandbox, pk_live_ for production
// All requests use Bearer token auth
const headers = {
'Authorization': 'Bearer pk_live_a1b2c3...',
'Content-Type': 'application/json',
}
// Test mode — no real letters sent
// pk_test_xxx → sandbox environment
// pk_live_xxx → productionPricing
Pay per action. No surprises.
| Action | Price | Notes |
|---|---|---|
| Create case (postal) | £3.50 | Includes letter + tracked delivery |
| Create case (digital only) | £1.00 | Email + SMS OTP |
| Identity Check | £0.15 | Email-only cross-tenant lookup |
| Address Match | £0.30 | Email + address cross-tenant lookup |
| Hash Verification | £0.15 | GDPR-friendly, no PII transmitted |
| Platform fee | £10/month | Account maintenance |
Get started in 3 steps.
Create an account
Sign up for a free trial. No credit card required.
Get API keys
Generate test and live keys from Settings in your dashboard.
Make your first query
Call any endpoint with your API key. Sandbox mode for safe testing.