API Reference

Base URL: https://www.workreferences.org

GET/api/verify/{id}

Verify a Reference

Verify an employment reference by UUID. Returns the verification status, reference details, and tenant information. No authentication required.

Parameters

Name	In	Type	Description
id	path	UUID	Reference UUID

Response

200 OK

{
  "status": "gold",           // "gold" | "silver" | "invalid"
  "reference": {
    "id": "uuid",
    "candidateName": "James Holloway",
    "jsonPayload": {
      "name": "James Holloway",
      "role": "Baggage Handler",
      "dates": "June 2021 – December 2024",
      "text": "James was a reliable and hardworking...",
      "nonce": "uuid"
    },
    "signature": "base64...",
    "revoked": false,
    "expiresAt": null,
    "createdAt": "2026-01-15T10:30:00Z"
  },
  "tenant": {
    "domain": "example.com",
    "publicKey": "base64...",
    "keySelector": "REF1"
  },
  "signatureValid": true,
  "dnsVerified": true
}

Examples

curl

curl https://www.workreferences.org/api/verify/550e8400-e29b-41d4-a716-446655440000

JavaScript

const res = await fetch(
  'https://www.workreferences.org/api/verify/550e8400-e29b-41d4-a716-446655440000'
);
const data = await res.json();
console.log(data.status); // "gold", "silver", or "invalid"

Python

import requests

res = requests.get(
    'https://www.workreferences.org/api/verify/550e8400-e29b-41d4-a716-446655440000'
)
data = res.json()
print(data['status'])  # "gold", "silver", or "invalid"

POST/api/verify/{id}

Verify with PDF Hash Check

Same as GET but also checks that an uploaded PDF matches the stored hash. Send the PDF as multipart form data.

Additional Response Field

{
  "pdfHashMatch": true   // whether uploaded PDF matches stored hash
}

curl

curl -X POST https://www.workreferences.org/api/verify/REFERENCE_UUID \
  -F "pdf=@reference.pdf"

POST/api/tenants/lookup

Look Up Tenant

Check if a domain is registered as a Work References tenant. Returns the public key and DNS verification status.

Request

{
  "domain": "example.com"
}

200 OK

{
  "found": true,
  "tenant": {
    "domain": "example.com",
    "publicKey": "base64...",
    "keySelector": "REF1",
    "isDnsVerified": true
  }
}

curl

curl -X POST https://www.workreferences.org/api/tenants/lookup \
  -H 'Content-Type: application/json' \
  -d '{"domain": "example.com"}'

GET/api/dns/check

Check DNS Record

Check if a domain has the Work References DNS TXT record configured. Public, no auth required. Rate limited to 60/min per IP.

Query Parameters

Name	Type	Description
domain	string	Domain to check (e.g. example.com)

200 OK (found)

{
  "domain": "example.com",
  "found": true,
  "record": "v=workreferences1; k=ed25519; p=abc123...",
  "selector": "REF1",
  "host": "REF1._workreferences.example.com",
  "valid": true
}

200 OK (not found)

{
  "domain": "example.com",
  "found": false,
  "record": null,
  "selector": "REF1",
  "host": "REF1._workreferences.example.com",
  "valid": false
}

curl

curl 'https://www.workreferences.org/api/dns/check?domain=example.com'

POST/api/partners/references

Create a Reference

Create a cryptographically signed employment reference. Requires authentication via per-tenant API key or global partner key. The signing password is always required to decrypt the private key for signing.

Authentication

Per-tenant key: x-api-key: rp_... or Authorization: Bearer rp_...
Global key: x-partner-key: <key>

Request Body

Field	Type	Max	Notes
tenantDomain	string	—	Required for global key; optional for per-tenant key
candidateName	string	200	Candidate full name
role	string	200	Job title / role
dates	string	100	Employment dates
text	string	10000	Reference text
signingPassword	string	—	Decrypts private key for signing

200 OK

{
  "success": true,
  "reference": {
    "id": "uuid",
    "candidateName": "Jane Smith",
    "pdfHash": "sha256hex..."
  }
}

Examples

curl

curl -X POST https://www.workreferences.org/api/partners/references \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: rp_your_api_key_here' \
  -d '{
    "candidateName": "Jane Smith",
    "role": "Software Engineer",
    "dates": "Jan 2022 – Dec 2024",
    "text": "Jane was an exceptional team member...",
    "signingPassword": "your-signing-password"
  }'

JavaScript

const res = await fetch(
  'https://www.workreferences.org/api/partners/references',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'rp_your_api_key_here',
    },
    body: JSON.stringify({
      candidateName: 'Jane Smith',
      role: 'Software Engineer',
      dates: 'Jan 2022 – Dec 2024',
      text: 'Jane was an exceptional team member...',
      signingPassword: 'your-signing-password',
    }),
  }
);
const data = await res.json();
console.log(data.reference.id);

Python

import requests

res = requests.post(
    'https://www.workreferences.org/api/partners/references',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'rp_your_api_key_here',
    },
    json={
        'candidateName': 'Jane Smith',
        'role': 'Software Engineer',
        'dates': 'Jan 2022 – Dec 2024',
        'text': 'Jane was an exceptional team member...',
        'signingPassword': 'your-signing-password',
    },
)
data = res.json()
print(data['reference']['id'])

GET/api/health

Health Check

200 OK

{ "status": "ok" }

Error Responses

All errors return a JSON object with an error field:

{ "error": "Human-readable error message" }

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
404	Not found — reference or tenant doesn't exist
429	Rate limited — includes `retryAfter` in seconds
500	Internal server error