> ## 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

> Add candidates (name and mobile number) to one of your enrichments. Record starts contacting them straight away: there is no separate start step. If the questions are still being prepared, the campaign waits and goes out by itself. Returns `campaign_id`, the candidates and every row that was skipped. Credits are charged per candidate added and checked for the whole batch first.

**Scope:** `enrichment:campaigns` · **Idempotency-Key:** optional

> **This contacts real candidates.** Build against a TEST key first.



## OpenAPI

````yaml /enrichment-api/api-reference/openapi.json post /enrichments/{enrichment_id}/campaigns
openapi: 3.1.0
info:
  title: Record Enrichment API
  version: 1.0.0
  description: >-
    Collect work, location, shift and salary details from your own candidate
    database. 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: Enrichment API
security: []
tags:
  - name: Enrichments
  - name: Enrichment campaigns
  - name: Enrichment candidates
  - name: Enrichment results
  - name: Enrichment credits
paths:
  /enrichments/{enrichment_id}/campaigns:
    post:
      tags:
        - Enrichment campaigns
      summary: Create a campaign
      description: >-
        Add candidates (name and mobile number) to one of your enrichments.
        Record starts contacting them straight away: there is no separate start
        step. If the questions are still being prepared, the campaign waits and
        goes out by itself. Returns `campaign_id`, the candidates and every row
        that was skipped. Credits are charged per candidate added and checked
        for the whole batch first.


        **Scope:** `enrichment:campaigns` · **Idempotency-Key:** optional


        > **This contacts real candidates.** Build against a TEST key first.
      operationId: createEnrichmentCampaign
      parameters:
        - name: enrichment_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^WF_[A-Z]{2}_[A-Z0-9]{10,40}$
          example: WF_EN_261121094822026AEDRUB86TQVSML
        - 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:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Campaign name, 1–200 characters.
                language:
                  type: string
                  enum:
                    - english
                    - tamil
                    - hindi
                    - kannada
                    - telugu
                    - malayalam
                    - bengali
                    - marathi
                  description: >-
                    Invite language; defaults to the enrichment's schedule
                    language
                candidates:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 200
                      phone_number:
                        type: string
                        minLength: 8
                        maxLength: 20
                        description: 'An Indian mobile number: 10 digits, or with +91'
                      external_id:
                        type: string
                        pattern: ^[A-Za-z0-9._:-]{1,128}$
                        description: >-
                          Your own id for the candidate; returned with their
                          status and results
                    required:
                      - name
                      - phone_number
                    additionalProperties: false
                  minItems: 1
                  maxItems: 1000
                  description: >-
                    Required. 1 to 1,000 of `{ name, phone_number, external_id?
                    }`. `phone_number` is an Indian mobile: 10 digits, or with
                    `+91`. A row with an invalid number, a number that opted
                    out, or a number already earlier in the list is skipped and
                    returned in `skipped`; it never fails the call.
                    `external_id` comes back on every candidate and result.
              required:
                - name
                - candidates
              additionalProperties: false
            example:
              name: November talent pool
              candidates:
                - name: Ravi Kumar
                  phone_number: '9876543210'
                  external_id: cand-1001
                - name: Meena S
                  phone_number: '9123456780'
                  external_id: cand-1002
                - name: Test Number
                  phone_number: '0000000000'
      responses:
        '201':
          description: The new campaign, its candidates and the rows skipped
          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
                          enrichment_id:
                            type: string
                          name:
                            type: string
                          language:
                            type: string
                          status:
                            type: string
                            enum:
                              - sent
                              - paused
                              - completed
                              - cancelled
                            description: sent = live
                          awaiting_questions:
                            type: boolean
                            description: >-
                              true while the questions are still being prepared;
                              nothing goes out until they are
                          question_count:
                            type: integer
                          channels:
                            type: object
                            properties:
                              whatsapp:
                                type: boolean
                              voice_call:
                                type: boolean
                              sms:
                                type: boolean
                          rejected_count:
                            type: integer
                            description: Rows skipped at upload
                          created_at:
                            type: string
                          counts:
                            type: object
                            properties:
                              candidates:
                                type: integer
                              sent:
                                type: integer
                              completed:
                                type: integer
                      candidates:
                        type: array
                        items:
                          type: object
                          properties:
                            candidate_id:
                              type: string
                            external_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            name:
                              type: string
                            phone_number:
                              type: string
                      skipped:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                              description: Position in the candidates you sent, from 0
                            name:
                              type: string
                            phone_number:
                              type: string
                            reason:
                              type: string
                              enum:
                                - invalid_phone
                                - opted_out
                                - duplicate
                        description: >-
                          Every row left out and why. Skipped rows are never an
                          error
              example:
                success: true
                data:
                  campaign:
                    campaign_id: EC_261121095438377TFUX07WN2XT42V
                    enrichment_id: WF_EN_261121094822026AEDRUB86TQVSML
                    name: November talent pool
                    language: english
                    status: sent
                    awaiting_questions: true
                    question_count: 2
                    channels:
                      whatsapp: true
                      voice_call: true
                      sms: true
                    rejected_count: 1
                    created_at: '2026-11-10T10:30:45.000Z'
                    counts:
                      candidates: 2
                      sent: 0
                      completed: 0
                  candidates:
                    - candidate_id: 6f1d2c3e-8a4b-4c57-9d10-2b7e5a9c1f33
                      external_id: cand-1001
                      name: Ravi Kumar
                      phone_number: '+919876543210'
                    - candidate_id: 0c9b7e21-5d3f-4a68-b1e4-77a2c8d9e054
                      external_id: cand-1002
                      name: Meena S
                      phone_number: '+919123456780'
                  skipped:
                    - index: 2
                      name: Test Number
                      phone_number: '0000000000'
                      reason: invalid_phone
        '400':
          description: >-
            `VALIDATION_FAILED`: No candidate has a contactable number
            (`details` say why), or a field is missing or unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            `INSUFFICIENT_CREDITS`: The organisation's credits do not cover
            every candidate in the batch (live wallet for a live key, test
            wallet for a TEST key). Nothing is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `FORBIDDEN`: A TEST key would exceed 50 candidates in this
            enrichment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`NOT_FOUND`: No such enrichment, or it is archived.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            `DAILY_CAP`: The key has put its daily allowance of different people
            into campaigns (2,000, or 200 for a TEST key). Resets at midnight
            IST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
          SecretKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            pcall POST
            "/api/v1/partner/enrichments/WF_EN_261121094822026AEDRUB86TQVSML/campaigns"
            '{
              "name": "November talent pool",
              "candidates": [
                {
                  "name": "Ravi Kumar",
                  "phone_number": "9876543210",
                  "external_id": "cand-1001"
                },
                {
                  "name": "Meena S",
                  "phone_number": "9123456780",
                  "external_id": "cand-1002"
                },
                {
                  "name": "Test Number",
                  "phone_number": "0000000000"
                }
              ]
            }'
        - lang: javascript
          label: JavaScript
          source: >-
            const res = await call("POST",
            "/api/v1/partner/enrichments/WF_EN_261121094822026AEDRUB86TQVSML/campaigns",
            {
              "name": "November talent pool",
              "candidates": [
                {
                  "name": "Ravi Kumar",
                  "phone_number": "9876543210",
                  "external_id": "cand-1001"
                },
                {
                  "name": "Meena S",
                  "phone_number": "9123456780",
                  "external_id": "cand-1002"
                },
                {
                  "name": "Test Number",
                  "phone_number": "0000000000"
                }
              ]
            });

            const { data } = await res.json();
        - lang: python
          label: Python
          source: >-
            res = call("POST",
            "/api/v1/partner/enrichments/WF_EN_261121094822026AEDRUB86TQVSML/campaigns",
            {
                "name": "November talent pool",
                "candidates": [
                    {
                        "name": "Ravi Kumar",
                        "phone_number": "9876543210",
                        "external_id": "cand-1001"
                    },
                    {
                        "name": "Meena S",
                        "phone_number": "9123456780",
                        "external_id": "cand-1002"
                    },
                    {
                        "name": "Test Number",
                        "phone_number": "0000000000"
                    }
                ]
            })

            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
                - 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.