API reference

Except for the public OpenAPI document, every REST request requires your API key as a Bearer token in the Authorization header. Store the key on the server only.

curl https://merite.ai/api/v1/account \
  -H "Authorization: Bearer <api-key>"

The default limit is 60 requests per minute per API key. Admin keys are exempt. REST and MCP return 429 rate_limited, a Retry-After header, and error.retry_after in seconds when you exceed the limit.

Every REST response is JSON and includes a request_id. Errors always use { error: { code, message, … }, request_id }.

1. Create a project at no charge with POST /api/v1/projects.
2. Ask for each missing_fields value and add it with PATCH /api/v1/projects/{id} until state=ready.
3. Confirm the paid action, then call POST /api/v1/projects/{id}/source.
4. Check status no more than every 15–30 minutes until state=delivered.
5. Retrieve candidates by tier and page.
6. Show the list to a human and return candidate, role, and process feedback.

The state pending_release means: accepted — processing starts shortly. Delivery is usually completed within the same business day.

Nine business fields must be complete before sourcing starts. They may be omitted from POST and PATCH; the API returns each gap in missing_fields with an explanation. This is a successful clarification loop, not a 422 error. Only an invalid value that was supplied produces validation_error. Never invent intake values.

Required fields

Optional fields

The field descriptions below come directly from the German v1 OpenAPI contract and intentionally remain in German.

{
  "project_id": "d7c1a9f4-…",
  "state": "draft",
  "missing_fields": [
    {
      "field": "work_location_postal_code",
      "explanation": "PLZ des tatsächlichen Arbeitsorts; für Deutschland fünfstellig. Bestimmt den Standort der Suche."
    }
  ],
  "next_step": "Fehlende Felder per PATCH /v1/projects/{id} ergänzen.",
  "request_id": "8f0a1c2e-…"
}

These operations are rendered directly from the published OpenAPI object. Status codes on the right list every documented response. The v1 endpoint summaries and descriptions intentionally remain in German.

GET /api/v1/projects/{id}/candidates becomes available at state=delivered. Filter tier by contact, borderline, or evaluated. offset starts at 0; limit defaults to 100 and cannot exceed 500.

public_identifier is the stable identity key. Never match candidates by name. Internal scores and the evaluation contract are never returned on customer-facing paths. reasoning is omitted entirely when reasoning output is disabled.

Additional data lives inside error: purchase_urls for 402, missing_fields for an incomplete start, state for state conflicts, and retry_after for 429.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate-Limit erreicht (60 Anfragen/Minute). Bitte in 37s erneut versuchen.",
    "retry_after": 37
  },
  "request_id": "8f0a1c2e-…"
}

The HTTP response also includes Retry-After: 37.