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

> Create the questions you want candidates to answer and the window they are contacted in. It is created once and never edited: different questions mean a new enrichment. Returns `enrichment_id`. Record prepares translations and voice in the background: read the enrichment until `questions_status` is `ready`.

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



## OpenAPI

````yaml /enrichment-api/api-reference/openapi.json post /enrichments
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:
    post:
      tags:
        - Enrichments
      summary: Create an enrichment
      description: >-
        Create the questions you want candidates to answer and the window they
        are contacted in. It is created once and never edited: different
        questions mean a new enrichment. Returns `enrichment_id`. Record
        prepares translations and voice in the background: read the enrichment
        until `questions_status` is `ready`.


        **Scope:** `enrichment:write` · **Idempotency-Key:** optional
      operationId: createEnrichment
      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:
                external_id:
                  type: string
                  pattern: ^[A-Za-z0-9._:-]{1,128}$
                  description: 'Your own id (1 to 128 of A-Z a-z 0-9 . _ : -)'
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Display name, 1–120 characters.
                description:
                  type: string
                  maxLength: 500
                  default: ''
                  description: Optional note, up to 500 characters.
                schedule:
                  type: object
                  properties:
                    language:
                      type: string
                      enum:
                        - english
                        - tamil
                        - hindi
                        - kannada
                        - telugu
                        - malayalam
                        - bengali
                        - marathi
                      default: english
                      description: >-
                        Opening language of messages and calls (the candidate
                        can switch)
                    start_time:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                      description: Send window start, HH:MM (24-hour)
                    end_time:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                      description: Send window end, HH:MM (24-hour)
                    days:
                      type: array
                      items:
                        type: string
                        enum:
                          - mon
                          - tue
                          - wed
                          - thu
                          - fri
                          - sat
                          - sun
                      minItems: 1
                      maxItems: 7
                      description: Days messages and calls may go out, each listed once
                      uniqueItems: true
                    timezone:
                      type: string
                      maxLength: 64
                    max_retries:
                      type: integer
                      minimum: 1
                      maximum: 20
                      description: Follow-up call attempts, 1 to 20
                    retry_after_hours:
                      type: integer
                      minimum: 1
                      maximum: 48
                      description: Hours before a retry, 1 to 48
                  required:
                    - start_time
                    - end_time
                    - days
                    - timezone
                    - max_retries
                    - retry_after_hours
                  additionalProperties: false
                  description: >-
                    Required. Send these six: `start_time` and `end_time`
                    ("HH:MM", start before end), `days` (mon…sun, each once),
                    `timezone` (IANA), `max_retries` 1 to 20 and
                    `retry_after_hours` 1 to 48. `language` is optional and
                    defaults to `english`: english, hindi, tamil, kannada,
                    telugu, malayalam, bengali or marathi.
                questions:
                  type: array
                  items:
                    type: object
                    properties:
                      question_text:
                        type: string
                        minLength: 1
                        maxLength: 300
                        description: What Record asks the candidate, up to 300 characters
                      type:
                        type: string
                        enum:
                          - yes_no
                          - voice
                        description: >-
                          yes_no is answered with a tap, voice is spoken or
                          recorded
                      preferred_answer:
                        type: string
                        enum:
                          - 'yes'
                          - 'no'
                        description: >-
                          Required for yes_no: the answer that counts as
                          qualified
                      required:
                        type: boolean
                        default: true
                        description: >-
                          A candidate completes only after answering every
                          required question
                    required:
                      - question_text
                      - type
                    additionalProperties: false
                  minItems: 1
                  maxItems: 15
                  description: >-
                    1 to 15 questions. An enrichment is never edited: different
                    questions mean a new enrichment
              required:
                - name
                - schedule
                - questions
              additionalProperties: false
            example:
              external_id: enr-chennai-warehouse
              name: Warehouse talent pool - Chennai
              schedule:
                language: english
                start_time: '10:00'
                end_time: '18:00'
                days:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                timezone: Asia/Kolkata
                max_retries: 3
                retry_after_hours: 4
              questions:
                - question_text: Are you open to a new job right now?
                  type: yes_no
                  preferred_answer: 'yes'
                  required: true
                - question_text: Tell us about the work you do and where you want to work.
                  type: voice
                  required: true
      responses:
        '201':
          description: The new enrichment
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      enrichment_id:
                        type: string
                      external_id:
                        anyOf:
                          - type: string
                          - type: 'null'
                      name:
                        type: string
                      description:
                        type: string
                      status:
                        type: string
                        enum:
                          - active
                          - archived
                      questions_status:
                        type: string
                        enum:
                          - pending
                          - ready
                          - failed
                        description: >-
                          Translation and voice of the questions. Campaigns wait
                          for ready, then go out by themselves; failed is
                          retried when you create a campaign
                      delivery:
                        type: object
                        properties:
                          whatsapp:
                            type: boolean
                          voice_call:
                            type: boolean
                          sms:
                            type: boolean
                      schedule:
                        type: object
                        properties:
                          language:
                            type: string
                          start_time:
                            type: string
                          end_time:
                            type: string
                          days:
                            type: array
                            items:
                              type: string
                          timezone:
                            type: string
                          max_retries:
                            type: integer
                          retry_after_hours:
                            type: integer
                      question_count:
                        type: integer
                      counts:
                        type: object
                        properties:
                          campaigns:
                            type: integer
                          candidates:
                            type: integer
                          sent:
                            type: integer
                            description: Candidates whose WhatsApp invite went out
                          completed:
                            type: integer
                            description: >-
                              Candidates who finished, including those who
                              declined
                      is_external:
                        type: boolean
                        description: >-
                          true when created through the Partner API, false when
                          made in the Record playground
                      created_at:
                        type: string
                      updated_at:
                        type: string
                      questions:
                        type: array
                        items:
                          type: object
                          properties:
                            question_id:
                              type: string
                            order:
                              type: integer
                            question_text:
                              type: string
                            short_form:
                              type: string
                            type:
                              type: string
                              enum:
                                - yes_no
                                - voice
                            preferred_answer:
                              anyOf:
                                - type: string
                                - type: 'null'
                            required:
                              type: boolean
              example:
                success: true
                data:
                  enrichment_id: WF_EN_261121094822026AEDRUB86TQVSML
                  external_id: enr-chennai-warehouse
                  name: Warehouse talent pool - Chennai
                  description: ''
                  status: active
                  questions_status: pending
                  delivery:
                    whatsapp: true
                    voice_call: true
                    sms: true
                  schedule:
                    language: english
                    start_time: '10:00'
                    end_time: '18:00'
                    days:
                      - mon
                      - tue
                      - wed
                      - thu
                      - fri
                      - sat
                    timezone: Asia/Kolkata
                    max_retries: 3
                    retry_after_hours: 4
                  question_count: 2
                  counts:
                    campaigns: 0
                    candidates: 0
                    sent: 0
                    completed: 0
                  is_external: true
                  created_at: '2026-11-10T10:15:30.000Z'
                  updated_at: '2026-11-10T10:15:30.000Z'
                  questions:
                    - question_id: eqq_cc9800817588972e
                      order: 0
                      question_text: Are you open to a new job right now?
                      short_form: Open to work
                      type: yes_no
                      preferred_answer: 'yes'
                      required: true
                    - question_id: eqq_7a31f0c2d95b84e6
                      order: 1
                      question_text: >-
                        Tell us about the work you do and where you want to
                        work.
                      short_form: Work and location
                      type: voice
                      preferred_answer: null
                      required: true
        '400':
          description: >-
            `VALIDATION_FAILED`: `name`, `schedule` or `questions` missing, a
            `yes_no` question without `preferred_answer`, `start_time` not
            before `end_time`, an unknown language, empty or repeated `days`, or
            an unknown field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `FORBIDDEN`: A TEST key's organisation already has 5 active
            enrichments. Archive one in the Record playground.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`CONFLICT`: `external_id` is already used by another enrichment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
          SecretKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            pcall POST "/api/v1/partner/enrichments" '{
              "external_id": "enr-chennai-warehouse",
              "name": "Warehouse talent pool - Chennai",
              "schedule": {
                "language": "english",
                "start_time": "10:00",
                "end_time": "18:00",
                "days": [
                  "mon",
                  "tue",
                  "wed",
                  "thu",
                  "fri",
                  "sat"
                ],
                "timezone": "Asia/Kolkata",
                "max_retries": 3,
                "retry_after_hours": 4
              },
              "questions": [
                {
                  "question_text": "Are you open to a new job right now?",
                  "type": "yes_no",
                  "preferred_answer": "yes",
                  "required": true
                },
                {
                  "question_text": "Tell us about the work you do and where you want to work.",
                  "type": "voice",
                  "required": true
                }
              ]
            }'
        - lang: javascript
          label: JavaScript
          source: |-
            const res = await call("POST", "/api/v1/partner/enrichments", {
              "external_id": "enr-chennai-warehouse",
              "name": "Warehouse talent pool - Chennai",
              "schedule": {
                "language": "english",
                "start_time": "10:00",
                "end_time": "18:00",
                "days": [
                  "mon",
                  "tue",
                  "wed",
                  "thu",
                  "fri",
                  "sat"
                ],
                "timezone": "Asia/Kolkata",
                "max_retries": 3,
                "retry_after_hours": 4
              },
              "questions": [
                {
                  "question_text": "Are you open to a new job right now?",
                  "type": "yes_no",
                  "preferred_answer": "yes",
                  "required": true
                },
                {
                  "question_text": "Tell us about the work you do and where you want to work.",
                  "type": "voice",
                  "required": true
                }
              ]
            });
            const { data } = await res.json();
        - lang: python
          label: Python
          source: |-
            res = call("POST", "/api/v1/partner/enrichments", {
                "external_id": "enr-chennai-warehouse",
                "name": "Warehouse talent pool - Chennai",
                "schedule": {
                    "language": "english",
                    "start_time": "10:00",
                    "end_time": "18:00",
                    "days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri",
                        "sat"
                    ],
                    "timezone": "Asia/Kolkata",
                    "max_retries": 3,
                    "retry_after_hours": 4
                },
                "questions": [
                    {
                        "question_text": "Are you open to a new job right now?",
                        "type": "yes_no",
                        "preferred_answer": "yes",
                        "required": True
                    },
                    {
                        "question_text": "Tell us about the work you do and where you want to work.",
                        "type": "voice",
                        "required": True
                    }
                ]
            })
            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.