Developer Quickstart

This guide is for customer developers, partner systems, and agent builders integrating with Veref.

Choose an integration path

Path	Use when
HTTP API	A backend service needs to start, inspect, or advance reference checks
`veref` CLI	An agent or technical operator needs a local headless workflow surface
Recruiter app	A human recruiter needs to issue keys, review evidence, or approve reports

Get an API key

Create a tenant-scoped API key from the recruiter app, through veref login, or through the Clerk-authenticated API key management route.

For reference-check automation, start with:


["references:read", "references:write", "valuations:write", "reports:write"]

Store the plaintext token immediately. Veref shows it once and stores only a hashed form.

Authenticate requests

Pass the token with either bearer auth or x-api-key:


Authorization: Bearer vrf_live_abc123def456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


x-api-key: vrf_live_abc123def456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Use live keys for production tenant data and test keys for sandbox data. A key can only access the tenant and environment it was issued for.

Start a reference check

Use the API-key route:


POST /v1/api/reference-requests

For candidate-led intake, send launchMode: "candidate_intake". For already-known referees, send launchMode: "manual_references" and include referee contacts with both email and phone.

Agents can use the CLI equivalent:


veref references start --stdin --format json < reference-request.json

Inspect and advance work

Common API-key routes:

Method	Path	Purpose
`GET`	`/v1/api/reference-requests/:requestId`	Read request state
`POST`	`/v1/api/reference-requests/:requestId/lifecycle`	Advance lifecycle state
`POST`	`/v1/api/reference-requests/:requestId/valuation/draft`	Generate or preview a valuation draft
`POST`	`/v1/api/reference-requests/:requestId/valuation/approve`	Approve report package
`POST`	`/v1/api/reference-requests/:requestId/share`	Create a customer share link
`POST`	`/v1/api/agent`	Ask the Veref workspace agent

The API key supplies tenant and recruiter identity. External callers should not send or choose tenantId or recruiterId.

Production checklist

Issue least-privilege scoped keys.
Keep test and live environments separate.
Treat token prefixes as log-safe and token secrets as passwords.
Rotate keys when access changes.
Use API routes for workflow state and ops routes only for coordination messages.
Expect webhooks to arrive in a follow-up release; v1 integration is request/response.