Post your jobs to Referio, programmatically

Grab an API key from Settings → API keys, then send a single POST. The job goes live the moment it's accepted.

curl -X POST https://referio.io/api/v1/jobs \
  -H "Authorization: Bearer $REFERIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Platform Engineer",
    "description": "Own our build and deploy pipeline end to end. Kubernetes, Go, and a small, kind team.",
    "referral_fee_amount": 8000,
    "referral_fee_currency": "USD",
    "location": "London or remote (UK)",
    "work_mode": "remote",
    "employment_type": "full_time",
    "tags": ["golang", "kubernetes", "platform"],
    "external_id": "ats-job-4471"
  }'

A 201 Created response comes back with the stored job, including its slug (its public URL) and the fee converted to USD.

HTTP/1.1 201 Created
{
  "job": {
    "id": "8f3c…",
    "slug": "senior-platform-engineer",
    "status": "active",
    "referral_fee_amount": 8000,
    "referral_fee_currency": "USD",
    "referral_fee_usd": 8000,
    "external_id": "ats-job-4471"
  }
}

Every request authenticates with a Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

There are two kinds of key:

Treat keys like passwords. Send them only over HTTPS, never embed them in client-side code, and rotate (revoke & reissue) them if one leaks.

Referio exists so that referring great people is worth real money. That's why every job must carry a referral fee worth at least US$5,000. You can quote the fee in any supported currency — the API converts it to USD at the current exchange rate and rejects anything below the minimum with a 422.

Example — mark a role as filled:

curl -X PATCH https://referio.io/api/v1/jobs/8f3c… \
  -H "Authorization: Bearer $REFERIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "filled" }'

The body for POST /api/v1/jobs (and the editable fields for PATCH). Unknown fields are ignored.

Pass your own external_id on every job. The first call creates the job; any later call with the same external_id updates the existing one instead of creating a duplicate. This makes syncs from an ATS safe to retry and replay — you can push your whole board on a schedule without fear of duplicates.

Success returns the stored job object. Validation problems return a 422 with a details object describing each field.

HTTP/1.1 422 Unprocessable Entity
{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "title": ["Title is too short."]
    }
  }
}

If you run an applicant tracking system or a job-posting platform, a single platform key lets you post for all of your employer customers. Identify each employer with employer_emailon the job body — Referio provisions the employer account automatically the first time it sees a new address, so there's no onboarding step to build.

curl -X POST https://referio.io/api/v1/jobs \
  -H "Authorization: Bearer $REFERIO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_email": "talent@acme.com",
    "employer_name": "Acme Corp",
    "title": "Staff Designer",
    "description": "Lead design across our flagship product. Strong systems thinking required.",
    "referral_fee_amount": 6500,
    "referral_fee_currency": "GBP",
    "external_id": "acme-217"
  }'

Combine this with external_idand you can mirror an entire customer's job board into Referio idempotently, on whatever schedule suits you.

This API is designed to be discoverable and safe for autonomous agents. If you're an agent integrating Referio, here's the short version:

• Discover the schema by sending GET https://referio.io/api/v1. It returns auth rules, constraints, and the full request body shape as JSON — no key needed.
• Authenticate with Authorization: Bearer <key> on every write.
• Honour the fee minimum: referral_fee_amount must convert to ≥ US$5,000, or the write is rejected with 422. Read the error message and adjust.
• Be idempotent: always send a stable external_id so retries never create duplicates.
• Required fields are title, description, referral_fee_amount, and referral_fee_currency (plus employer_email on a platform key). Everything else has sensible defaults.