Quickstart

Use a TEST key while you build. Campaigns contact real people even in test mode, and live campaigns spend credits.

Set up your key and secret

You only need your key id and secret. Copy the call() helper for your language from Authentication: it makes the timestamp, signature and Idempotency-Key for you. Or skip the code and use Try it on any API reference page. Then check your key with a read:

const res = await call("GET", "/api/v1/partner/workflows?limit=1");
console.log(res.status, await res.json());

res = call("GET", "/api/v1/partner/workflows?limit=1")
print(res.status_code, res.json())

A 200 with "success": true means you are ready.

Create a workflow

A workflow sets how and when candidates are contacted. Create it once and reuse it for every job.

const res = await call("POST", "/api/v1/partner/workflows", {
  name: "Warehouse associates - Chennai",
  schedule: {
    start_time: "09:00",
    end_time: "19:00",
    days: ["mon", "tue", "wed", "thu", "fri", "sat"],
    timezone: "Asia/Kolkata",
    max_retries: 3,
    retry_after_hours: 6,
  },
});
const { workflow_id } = (await res.json()).data;

res = call("POST", "/api/v1/partner/workflows", {
    "name": "Warehouse associates - Chennai",
    "schedule": {
        "start_time": "09:00",
        "end_time": "19:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat"],
        "timezone": "Asia/Kolkata",
        "max_retries": 3,
        "retry_after_hours": 6,
    },
})
workflow_id = res.json()["data"]["workflow_id"]

Create a job mandate

The mandate is the job: 5 to 10 skills (at most 3 with verify: true) and up to 5 screening questions (10 with enrichment only). Find skill ids with GET /skills/search.

const res = await call("POST", "/api/v1/partner/mandates", {
  workflow_id,
  title: "Warehouse Associate (Forklift)",
  company_name: "Acme Logistics Pvt Ltd",
  location: { city: "Chennai", state: "Tamil Nadu" },
  skills: [
    { skill_id: "sk_36440", verify: true },
    { skill_id: "sk_38973", verify: true },
    { skill_id: "sk_38824", verify: true },
    { skill_id: "sk_2338" },
    { skill_id: "sk_2452" },
  ],
  enrichment_questions: [
    { key: "has_licence", type: "yes_no", text: "Do you hold a valid forklift licence?", knockout: "no" },
  ],
});
const { mandate_id } = (await res.json()).data; // status: "preparing"

res = call("POST", "/api/v1/partner/mandates", {
    "workflow_id": workflow_id,
    "title": "Warehouse Associate (Forklift)",
    "company_name": "Acme Logistics Pvt Ltd",
    "location": {"city": "Chennai", "state": "Tamil Nadu"},
    "skills": [
        {"skill_id": "sk_36440", "verify": True},
        {"skill_id": "sk_38973", "verify": True},
        {"skill_id": "sk_38824", "verify": True},
        {"skill_id": "sk_2338"},
        {"skill_id": "sk_2452"},
    ],
    "enrichment_questions": [
        {"key": "has_licence", "type": "yes_no", "text": "Do you hold a valid forklift licence?", "knockout": "no"},
    ],
})
mandate_id = res.json()["data"]["mandate_id"]  # status: "preparing"

The answer is 202 Accepted with status: "preparing" while Record writes the skill questions. GET /api/v1/partner/mandates/{mandate_id} shows ready when they are done. You do not have to wait: a campaign created now goes out by itself once the mandate is ready.

Give Record an HTTPS URL. Each finished candidate’s result is posted there, signed with your secret. See Webhooks to verify the signature.

await call("POST", "/api/v1/partner/webhooks/endpoints", {
  url: "https://ats.example.com/hooks/record",
  event_types: ["candidate.result"],
});

call("POST", "/api/v1/partner/webhooks/endpoints", {
    "url": "https://ats.example.com/hooks/record",
    "event_types": ["candidate.result"],
})

Create a campaign

Send the candidates. With a TEST key, use only the phone numbers Record listed for your key.

const res = await call("POST", "/api/v1/partner/campaigns", {
  mandate_id,
  name: "Warehouse Associate - October batch",
  start: "now",
  candidates: [{ external_id: "cand-88231", name: "Ravi Kumar", phone: "+91 98765 43210" }],
});
const { campaign, accepted, rejected } = (await res.json()).data;

res = call("POST", "/api/v1/partner/campaigns", {
    "mandate_id": mandate_id,
    "name": "Warehouse Associate - October batch",
    "start": "now",
    "candidates": [{"external_id": "cand-88231", "name": "Ravi Kumar", "phone": "+91 98765 43210"}],
})
data = res.json()["data"]
campaign_id = data["campaign"]["campaign_id"]

Numbers that cannot be used come back in rejected with a reason. The rest go ahead.

Receive results

When a candidate finishes, your webhook receives a candidate.result event with their result record. No public URL? Pull the events instead. To catch up or check, read the results directly:

const res = await call("GET", `/api/v1/partner/campaigns/${campaign.campaign_id}/results`);
const { items } = (await res.json()).data;

res = call("GET", f"/api/v1/partner/campaigns/{campaign_id}/results")
items = res.json()["data"]["items"]

Get started

Integration

Reference

Next steps

Job mandates

Errors

​Next steps

Job mandates

Errors

Next steps