> ## Documentation Index > Fetch the complete documentation index at: https://docs.userecord.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a campaign > Send your candidates (name + phone) for a mandate. Record contacts and verifies them. Returns `campaign_id`. **Scope:** `campaigns:write` · **Idempotency-Key:** optional > **This contacts real candidates.** Build against a TEST key first. ## OpenAPI ````yaml /blue-collar-api/api-reference/openapi.json post /campaigns openapi: 3.1.0 info: title: Record Blue Collar API version: 1.0.0 description: >- Run Record candidate verification from your own system. You need two things: your **key id** and your **secret**. Everything else is generated. See Authentication for how. servers: - url: https://api-bc.userecord.io/api/v1/partner description: Blue Collar API security: [] tags: - name: Skills description: The skill taxonomy, read live a page at a time - name: Skill requests description: Ask Record to add a missing skill - name: Lookups description: >- Lookups for filling in a job mandate: places in India, the countries an abroad job can be in, and the employment types and shifts the playground offers - name: Workflows description: >- Your organisation's blue-collar workflows (read all; change and soft-delete only the ones you created) - name: Job mandates description: >- Your organisation's job mandates, addressed by Record's mandate_id (read all; change only the ones you created) - name: Campaigns description: Contact candidates for one of your jobs and verify them. Spends credits - name: Results description: >- What Record collected from each candidate: status (pending, completed, declined, failed) and an output of answers and verdicts - name: Events description: >- Pull your result events and acknowledge them: the safety net behind the webhook, and a way to receive results without exposing a URL - name: Webhooks description: >- Endpoints that Record POSTs result events to: signed, retried until you acknowledge, replayable - name: Analytics description: >- The workflow Overview analytics of the Record playground: funnel, channels, follow-ups, calls, drop-offs, languages (read-only, scope analytics:read) paths: /campaigns: post: tags: - Campaigns summary: Create a campaign description: >- Send your candidates (name + phone) for a mandate. Record contacts and verifies them. Returns `campaign_id`. **Scope:** `campaigns:write` · **Idempotency-Key:** optional > **This contacts real candidates.** Build against a TEST key first. operationId: createCampaign parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Optional. A retry with the same key returns the first answer (kept 24 h). Leave empty in Try it: a new one is made for every call. requestBody: required: true content: application/json: schema: type: object properties: mandate_id: type: string pattern: ^JM_[A-Z0-9]{10,40}$ description: >- Record's job mandate id: the mandate_id returned when you created the job mandate. Send this or job_id, not both job_id: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ description: >- Your own job id, if the mandate was created with one. Send this or mandate_id, not both name: type: string minLength: 1 maxLength: 120 description: Defaults to the job title and today's date external_id: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ description: Your own id for this campaign. Must be unique start: type: string enum: - now - manual description: >- now: send straight away. manual: create a draft and start it later language: type: string enum: - en - hi - ta - te - kn - ml description: The language candidates are contacted in. Default en candidates: type: array items: type: object properties: external_id: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ description: >- Your own id for this candidate. Comes back on every result, so you can match it to your record name: type: string minLength: 1 maxLength: 120 phone: type: string minLength: 1 maxLength: 30 description: >- A mobile number: 10 digits (98765 43210), or with the country code (+91 98765 43210). Never returned by this API metadata: type: object additionalProperties: anyOf: - type: string maxLength: 200 - type: number - type: boolean description: >- Up to 10 fields of your own (your application id, requisition...). Returned unchanged in `metadata` of every result and event. Needs `external_id` required: - name - phone additionalProperties: false minItems: 1 maxItems: 1000 description: >- 1–1,000 of `{ name, phone, external_id? }`. Phone: 10 digits or with country code. Bad numbers come back in `rejected`. required: - start - candidates additionalProperties: false example: mandate_id: JM_261009101612456H3N8W2L5C9V1Z4 name: Warehouse Associate - October batch external_id: ats-campaign-5521 start: now language: en candidates: - external_id: cand-88231 name: Ravi Kumar phone: 98765 43210 - external_id: cand-88232 name: Meena Devi phone: +91 98123 45678 - external_id: cand-88233 name: Karthik Raj phone: 99000 11122 responses: '201': description: >- The campaign, how many candidates were accepted, and any that were left out content: application/json: schema: type: object properties: success: const: true type: boolean message: type: string data: type: object properties: campaign: type: object properties: campaign_id: type: string external_id: anyOf: - type: string - type: 'null' mandate_id: type: string description: >- Record's job mandate id: the mandate this campaign runs under job_id: anyOf: - type: string - type: 'null' description: >- Your job id; null for a mandate created without one name: type: string status: type: string enum: - draft - waiting_for_questions - blocked - sending - paused - completed - cancelled description: >- draft: not started. waiting_for_questions: started, goes out by itself once the job's questions are ready. blocked: see `blocked`. sending: candidates are being contacted. blocked: anyOf: - type: object properties: reason: type: string message: type: string - type: 'null' description: >- Why a started campaign is not going out, when it is stuck language: type: string candidates: type: object properties: total: type: integer sent: type: integer description: Contacted queued: type: integer description: Waiting to be contacted failed: type: integer description: Could not be reached at all created_at: type: string started_at: anyOf: - type: string - type: 'null' sent_at: anyOf: - type: string - type: 'null' paused_at: anyOf: - type: string - type: 'null' accepted: type: integer rejected: type: array items: type: object properties: index: type: integer description: Position in the candidates you sent external_id: anyOf: - type: string - type: 'null' reason: type: string enum: - invalid_phone - duplicate_in_request - already_in_campaign credits_reserved: type: integer description: >- Credits set aside for this campaign (0 when skill verification is off) example: success: true data: campaign: campaign_id: asmnt_9f2c41d7a8b3e65f external_id: ats-campaign-5521 mandate_id: JM_261009101612456H3N8W2L5C9V1Z4 job_id: job-10452 name: Warehouse Associate - October batch status: waiting_for_questions blocked: null language: english candidates: total: 3 sent: 0 queued: 3 failed: 0 created_at: '2026-10-05T09:12:44.000Z' started_at: '2026-10-05T09:12:45.000Z' sent_at: null paused_at: null accepted: 3 rejected: [] credits_reserved: 3 '400': description: >- `VALIDATION_FAILED`: Both or neither of `mandate_id` / `job_id`, or no usable phone number. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- `INSUFFICIENT_CREDITS`: Not enough credits (1 per candidate when skill verification is on). content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- `FORBIDDEN`: TEST key with a number not on its list, or the mandate was made in the playground. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`NOT_FOUND`: No such mandate.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '`CONFLICT`: Mandate is archived, or campaign `external_id` is taken.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`DAILY_CAP`: 2,000 different candidates already added today.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKey: [] SecretKey: [] x-codeSamples: - lang: bash label: cURL source: |- pcall POST "/api/v1/partner/campaigns" '{ "mandate_id": "JM_261009101612456H3N8W2L5C9V1Z4", "name": "Warehouse Associate - October batch", "external_id": "ats-campaign-5521", "start": "now", "language": "en", "candidates": [ { "external_id": "cand-88231", "name": "Ravi Kumar", "phone": "98765 43210" }, { "external_id": "cand-88232", "name": "Meena Devi", "phone": "+91 98123 45678" }, { "external_id": "cand-88233", "name": "Karthik Raj", "phone": "99000 11122" } ] }' - lang: javascript label: JavaScript source: |- const res = await call("POST", "/api/v1/partner/campaigns", { "mandate_id": "JM_261009101612456H3N8W2L5C9V1Z4", "name": "Warehouse Associate - October batch", "external_id": "ats-campaign-5521", "start": "now", "language": "en", "candidates": [ { "external_id": "cand-88231", "name": "Ravi Kumar", "phone": "98765 43210" }, { "external_id": "cand-88232", "name": "Meena Devi", "phone": "+91 98123 45678" }, { "external_id": "cand-88233", "name": "Karthik Raj", "phone": "99000 11122" } ] }); const { data } = await res.json(); - lang: python label: Python source: |- res = call("POST", "/api/v1/partner/campaigns", { "mandate_id": "JM_261009101612456H3N8W2L5C9V1Z4", "name": "Warehouse Associate - October batch", "external_id": "ats-campaign-5521", "start": "now", "language": "en", "candidates": [ { "external_id": "cand-88231", "name": "Ravi Kumar", "phone": "98765 43210" }, { "external_id": "cand-88232", "name": "Meena Devi", "phone": "+91 98123 45678" }, { "external_id": "cand-88233", "name": "Karthik Raj", "phone": "99000 11122" } ] }) data = res.json()["data"] components: schemas: Error: type: object properties: success: const: false type: boolean error: type: object properties: code: type: string enum: - VALIDATION_FAILED - LIMIT_EXCEEDED - UNAUTHORIZED - SCOPE_MISSING - FORBIDDEN - HTTPS_REQUIRED - NOT_FOUND - CONFLICT - WORKFLOW_IN_USE - INSUFFICIENT_CREDITS - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_IN_PROGRESS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - RATE_LIMITED - COOLDOWN - DAILY_CAP - SERVICE_DISABLED - SERVER_ERROR message: type: string details: type: array items: type: object properties: path: type: string message: type: string request_id: type: string description: Quote it to Record support securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: Your key id, `VFN_TEST_…` or `VFN_LIVE_…`. Sent on every request. SecretKey: type: apiKey in: header name: x-secret-key description: >- Your secret, `VFN_SK_…`. **Not a real header, and never sent to the API.** It is only a form field for Try it, which uses it to sign your request in your browser. In your own code you sign each request with the secret and send `x-api-key`, `x-timestamp` and `x-signature` (see Authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.