> ## 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 job mandate > Create the job Record verifies candidates against. Returns `mandate_id`; questions are prepared in the background. **Scope:** `mandates:write` · **Idempotency-Key:** optional ## OpenAPI ````yaml /blue-collar-api/api-reference/openapi.json post /mandates 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: /mandates: post: tags: - Job mandates summary: Create a job mandate description: >- Create the job Record verifies candidates against. Returns `mandate_id`; questions are prepared in the background. **Scope:** `mandates:write` · **Idempotency-Key:** optional operationId: createMandate 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: workflow_id: type: string pattern: ^WF_[A-Z]{2}_[A-Z0-9]{10,40}$ description: One of your workflows title: type: string minLength: 1 maxLength: 200 description: Plain text, up to 200 characters. company_name: type: string minLength: 1 maxLength: 200 description: Plain text, up to 200 characters. location_type: type: string enum: - india - abroad description: >- Where the job is: "india" (default; give `location`) or "abroad" (give `countries`). Same as the playground's Abroad option location: type: object properties: city: type: string minLength: 1 maxLength: 100 state: type: string maxLength: 100 pincode: type: string pattern: ^\d{6}$ required: - city additionalProperties: false description: >- A place in India (find it with GET /locations). Leave it out for an abroad job countries: type: array items: type: string pattern: ^[A-Za-z]{2}$ maxItems: 20 description: >- Only with location_type "abroad": 1 to 10 ISO 3166-1 alpha-2 codes such as SG (list them with GET /countries). India is not selectable experience: type: object properties: min_years: type: integer minimum: 0 maximum: 50 max_years: type: integer minimum: 0 maximum: 50 required: - min_years - max_years additionalProperties: false description: Whole years, 0 to 50 openings: type: integer minimum: 1 maximum: 100000 description: Job details. `description` up to 1,500 characters. salary: type: object properties: min: type: number minimum: 0 maximum: 100000000 max: type: number minimum: 0 maximum: 100000000 currency: const: INR type: string default: INR period: const: month type: string default: month required: - min - max additionalProperties: false description: Job details. `description` up to 1,500 characters. description: type: string maxLength: 1500 description: Up to 1,500 characters (the question generator's limit) shift: type: string maxLength: 100 description: >- Use a value from GET /shifts so the playground shows it as a choice; any other text is kept as sent employment_type: type: string maxLength: 100 description: >- Use a value from GET /employment-types so the playground shows it as a choice; any other text is kept as sent owner: type: object properties: external_user_id: type: string minLength: 1 maxLength: 128 name: type: string maxLength: 200 required: - external_user_id additionalProperties: false description: The recruiter in your ATS; defaults to x-on-behalf-of methods: type: array items: type: string enum: - data_enrichment - skill_verification - interest_collection minItems: 1 maxItems: 3 description: >- Any non-empty mix; candidates always go enrichment → skills → interest. Omit to use the workflow's default. uniqueItems: true skills: type: array items: anyOf: - type: object properties: skill_id: type: string pattern: ^sk_\d{1,9}$ verify: type: boolean default: false description: At most 3 per mandate, and only verifiable skills required: - skill_id additionalProperties: false - type: object properties: name: type: string minLength: 2 maxLength: 120 pending: const: true type: boolean description: >- A skill you asked Record to add (POST /skill-requests); cannot be verified required: - name - pending additionalProperties: false minItems: 1 maxItems: 50 description: 5 to 10 recommended; fewer than 5 is a warning enrichment_questions: type: array items: type: object properties: key: type: string pattern: ^[A-Za-z0-9_.-]{1,64}$ description: Your id for the question; answers come back under it type: type: string enum: - yes_no - voice description: >- yes_no = a Yes / No question; voice = the candidate answers in their own words text: type: string minLength: 1 maxLength: 200 description: English knockout: type: string enum: - 'yes' - 'no' description: >- yes_no only: the answer ("yes" or "no") that marks the candidate not qualified required: type: boolean description: Default true required: - key - type - text additionalProperties: false maxItems: 50 description: >- 0 to 5 enrichment questions (up to 10 when data_enrichment is the only method) interest_collection: type: object properties: other_roles: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 10 additionalProperties: false description: >- `other_roles` is only saved and returned. It does not change what candidates are asked: the interest prompt is fixed, and `methods` switches it on or off. job_id: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ description: >- Optional: your own id for the job, kept with the mandate and returned as job_id. Leave it out to work with mandate_id alone required: - workflow_id - title - company_name - skills additionalProperties: false example: workflow_id: WF_BG_261009101530123K7M2P9Q4X7R5T8 title: Warehouse Associate (Forklift) company_name: Acme Logistics Pvt Ltd location_type: india location: city: Chennai state: Tamil Nadu pincode: '600001' experience: min_years: 1 max_years: 5 openings: 12 salary: min: 18000 max: 24000 currency: INR period: month description: >- Pick, pack and load orders in a busy warehouse. Forklift licence preferred. shift: Day shift employment_type: Full-time owner: external_user_id: recruiter_1042 name: Priya Nair methods: - data_enrichment - skill_verification - interest_collection 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 - name: Reach Truck Operation pending: true enrichment_questions: - key: has_licence type: yes_no text: Do you hold a valid forklift licence? knockout: 'no' required: true - key: why_this_job type: voice text: Tell us in your own words why you want this job. required: false interest_collection: other_roles: - Forklift Operator - Store Keeper responses: '202': description: 'Accepted: the mandate exists and its questions are being prepared' content: application/json: schema: type: object properties: success: const: true type: boolean message: type: string data: type: object properties: mandate_id: type: string job_id: anyOf: - type: string - type: 'null' description: >- Your job id; null for a mandate created without one (it is known by its mandate_id) status: type: string enum: - preparing - ready - failed - archived flow_version: type: integer methods: type: array items: type: string enum: - data_enrichment - skill_verification - interest_collection changed: type: boolean description: false when the same mandate was sent again warnings: type: array items: type: string example: success: true data: mandate_id: JM_261009101612456H3N8W2L5C9V1Z4 job_id: null status: preparing flow_version: 1 methods: - data_enrichment - skill_verification - interest_collection changed: true warnings: [] '400': description: >- `VALIDATION_FAILED`: Unknown skill, `verify` on a skill that cannot be verified, repeated skill / question key, a check without its data, `abroad` without `countries` (or with `location`), `countries` on an India job, an unknown or non-selectable country code, or experience above 50 years. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '`FORBIDDEN`: That workflow was made in the playground.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`NOT_FOUND`: `workflow_id` not found.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '`CONFLICT`: Workflow is archived, or `job_id` is already used.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- `LIMIT_EXCEEDED`: More than 10 skills, 3 verified skills or 5 questions. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKey: [] SecretKey: [] x-codeSamples: - lang: bash label: cURL source: |- pcall POST "/api/v1/partner/mandates" '{ "workflow_id": "WF_BG_261009101530123K7M2P9Q4X7R5T8", "title": "Warehouse Associate (Forklift)", "company_name": "Acme Logistics Pvt Ltd", "location_type": "india", "location": { "city": "Chennai", "state": "Tamil Nadu", "pincode": "600001" }, "experience": { "min_years": 1, "max_years": 5 }, "openings": 12, "salary": { "min": 18000, "max": 24000, "currency": "INR", "period": "month" }, "description": "Pick, pack and load orders in a busy warehouse. Forklift licence preferred.", "shift": "Day shift", "employment_type": "Full-time", "owner": { "external_user_id": "recruiter_1042", "name": "Priya Nair" }, "methods": [ "data_enrichment", "skill_verification", "interest_collection" ], "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" }, { "name": "Reach Truck Operation", "pending": true } ], "enrichment_questions": [ { "key": "has_licence", "type": "yes_no", "text": "Do you hold a valid forklift licence?", "knockout": "no", "required": true }, { "key": "why_this_job", "type": "voice", "text": "Tell us in your own words why you want this job.", "required": false } ], "interest_collection": { "other_roles": [ "Forklift Operator", "Store Keeper" ] } }' - lang: javascript label: JavaScript source: |- const res = await call("POST", "/api/v1/partner/mandates", { "workflow_id": "WF_BG_261009101530123K7M2P9Q4X7R5T8", "title": "Warehouse Associate (Forklift)", "company_name": "Acme Logistics Pvt Ltd", "location_type": "india", "location": { "city": "Chennai", "state": "Tamil Nadu", "pincode": "600001" }, "experience": { "min_years": 1, "max_years": 5 }, "openings": 12, "salary": { "min": 18000, "max": 24000, "currency": "INR", "period": "month" }, "description": "Pick, pack and load orders in a busy warehouse. Forklift licence preferred.", "shift": "Day shift", "employment_type": "Full-time", "owner": { "external_user_id": "recruiter_1042", "name": "Priya Nair" }, "methods": [ "data_enrichment", "skill_verification", "interest_collection" ], "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" }, { "name": "Reach Truck Operation", "pending": true } ], "enrichment_questions": [ { "key": "has_licence", "type": "yes_no", "text": "Do you hold a valid forklift licence?", "knockout": "no", "required": true }, { "key": "why_this_job", "type": "voice", "text": "Tell us in your own words why you want this job.", "required": false } ], "interest_collection": { "other_roles": [ "Forklift Operator", "Store Keeper" ] } }); const { data } = await res.json(); - lang: python label: Python source: |- res = call("POST", "/api/v1/partner/mandates", { "workflow_id": "WF_BG_261009101530123K7M2P9Q4X7R5T8", "title": "Warehouse Associate (Forklift)", "company_name": "Acme Logistics Pvt Ltd", "location_type": "india", "location": { "city": "Chennai", "state": "Tamil Nadu", "pincode": "600001" }, "experience": { "min_years": 1, "max_years": 5 }, "openings": 12, "salary": { "min": 18000, "max": 24000, "currency": "INR", "period": "month" }, "description": "Pick, pack and load orders in a busy warehouse. Forklift licence preferred.", "shift": "Day shift", "employment_type": "Full-time", "owner": { "external_user_id": "recruiter_1042", "name": "Priya Nair" }, "methods": [ "data_enrichment", "skill_verification", "interest_collection" ], "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" }, { "name": "Reach Truck Operation", "pending": True } ], "enrichment_questions": [ { "key": "has_licence", "type": "yes_no", "text": "Do you hold a valid forklift licence?", "knockout": "no", "required": True }, { "key": "why_this_job", "type": "voice", "text": "Tell us in your own words why you want this job.", "required": False } ], "interest_collection": { "other_roles": [ "Forklift Operator", "Store Keeper" ] } }) 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.