Reffolio API

How it works

The API mirrors the Reffolio workflow exactly. You create a request; Reffolio emails the previous employer a secure link; they complete a sector-specific form; the candidate consents; you receive a verified, tamper-evident record. You can be notified by webhook at each step, or poll for status.

1. Create a request — POST /v1/requests — get a request_id (status pending).
2. The referee completes the reference — you receive a referee_submitted webhook (status becomes awaiting_consent).
3. The candidate consents — you receive consent_granted and reference_received (status becomes received).
4. Read the reference — GET /v1/references/{id}.

Authentication

An organisation admin generates keys in the dashboard under API. The full key (rfl_live_…) is shown once — store it securely. Send it as a bearer token on every request:

Authorization: Bearer rfl_live_EXAMPLEKEY1234567890

Base URL:

https://reference-platform-production.up.railway.app

A quick check from your terminal:

curl -H "Authorization: Bearer rfl_live_..." \
  https://reference-platform-production.up.railway.app/v1/ping

Requests & references

{
  "worker_name": "Sam Jones",
  "worker_email": "sam@example.com",
  "referee_email": "manager@previousemployer.co.uk",
  "referee_name": "A. Manager",
  "prev_employer_name": "Previous Employer Ltd",
  "template_id": null,
  "message": "Optional note shown to the referee."
}

{
  "request_id": "...",
  "status": "pending",
  "email_sent": true,
  "domain_verified": true
}

{
  "request_id": "...",
  "status": "received",
  "candidate_name": "Sam Jones",
  "referee_email": "manager@previousemployer.co.uk",
  "consent_status": "granted",
  "reference": {
    "reference_id": "...",
    "ref_number": "REF-2026-000123",
    "content_hash": "770c44...",
    "readable": true
  }
}

[
  { "request_id": "...", "status": "awaiting_consent", "candidate_name": "Sam Jones", "consent_status": "pending" }
]

{
  "reference_id": "...",
  "ref_number": "REF-2026-000123",
  "candidate_name": "Sam Jones",
  "sector": "care",
  "content": { "...": "..." },
  "content_hash": "770c44...",
  "consent_status": "granted"
}

Request lifecycle

The status field on a request moves through these values:

Webhooks

Register a URL and Reffolio will POST a signed JSON payload when events happen. Polling (GET /v1/requests/{id}) is always available as a fallback.

{
  "url": "https://your-system.example.com/reffolio/hook",
  "events": ["referee_submitted", "consent_granted", "reference_received"]
}

{
  "id": "...",
  "url": "https://your-system.example.com/reffolio/hook",
  "events": ["referee_submitted", "consent_granted", "reference_received"],
  "active": true,
  "secret": "whsec_..."
}

[
  { "id": "...", "url": "...", "events": ["..."], "active": true, "last_status": 200 }
]

{
  "deleted": true,
  "id": "..."
}

Events

Payload & signature

Each delivery has this shape, with the event name and data:

{
  "event": "reference_received",
  "data": {
    "reference_id": "...",
    "ref_number": "REF-2026-000123"
  }
}

Verify authenticity using the X-Reffolio-Signature header, which is sha256= followed by the HMAC-SHA256 of the raw request body, keyed with your webhook secret:

import hmac, hashlib

def verify(secret, raw_body, header):
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Delivery is best-effort: respond with a 2xx status quickly. If your endpoint is unavailable, use polling to reconcile any missed events.

Errors

Errors return a JSON body { "detail": "..." } with a standard HTTP status:

Notes

• Keys are scoped to one organisation and only ever access that organisation’s own data.
• Requests created via the API send the same emails and follow the same consent flow as the dashboard.
• References are only readable once the candidate has granted consent.
• Keep your keys and webhook secrets safe. If a key is exposed, revoke it in the dashboard and generate a new one.