> ## Documentation Index > Fetch the complete documentation index at: https://docs.vort-sourcing.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a matching run > NOT idempotent: every accepted call starts a new run. Do not retry automatically on a timeout or 5xx. At most 3 `must` requirements. ## OpenAPI ````yaml /api-reference/openapi.yaml post /runs openapi: 3.1.0 info: title: Vort Partner API version: 1.0.0 summary: Server-to-server API for ATS vendors embedding Vort candidate matching. description: > Guides: [Integration flow](/integration-flow). UI rules: [UI specification](/ui-specification). Notices: [Notices](/notices). - Every call is server-to-server. `vpk_` keys and `vot_` org tokens MUST NOT reach a browser. - Clients MUST ignore unknown response fields; additive changes within v1 are non-breaking. - Notices with an unknown `code` MUST be rendered generically from `title` + `body`, styled by `severity`, placed by `slot`. - Rate limits are per partner (default 120/minute, 20,000/day); `429` carries `Retry-After`. - Sandbox ([Sandbox guide](/sandbox)): every sandbox response carries `x-vort-environment: sandbox`; names are masked, reveals are synthetic and free, `target_count` <= 20, 20 real runs per organization per 24 h, `cert-*` jobs run certification fixtures, and the sandbox-only headers `x-vort-sandbox-simulate` / `x-vort-sandbox-reveal-price` and route `POST /sandbox/webhooks/test` exist. None of these exist in production. contact: name: Vort partner support (always include the run_id) license: name: Proprietary identifier: LicenseRef-Vort-Proprietary servers: - url: https://vort-partner-api.vercel.app/sandbox/v1 description: Sandbox security: - partnerKey: [] orgToken: [] tags: - name: Activation description: Connect a customer organization by redeeming its one-time activation code. - name: Users description: Register the recruiters who act on runs (a field, never a credential). - name: Jobs description: Jobs the runs search for. - name: Runs description: Start runs and read their progress, notices and candidates. - name: Candidates description: Reveal candidate contact details (charges credits). - name: Decisions description: Report recruiter decisions and the notices shown (mandatory). - name: Sandbox description: >- Sandbox-only helpers (see the [Sandbox guide](/sandbox)). Not present in production (404). - name: Webhooks description: >- Events Vort posts to your registered HTTPS endpoint, signed with `x-vort-signature`. paths: /runs: post: tags: - Runs summary: Start a matching run description: > NOT idempotent: every accepted call starts a new run. Do not retry automatically on a timeout or 5xx. At most 3 `must` requirements. operationId: startRun parameters: - $ref: '#/components/parameters/Lang' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunRequest' example: job_external_id: job-4410 acting_user_external_id: u-88121 target_count: 30 requirements: - text: 5+ years of backend development in Go or Java kind: must - text: Production experience with Kafka kind: must - text: Payments or fintech domain kind: nice responses: '202': description: Run started. content: application/json: schema: $ref: '#/components/schemas/RunAccepted' example: run_id: 9f2b6c1e-3d4a-4e8f-b1c7-0a5d2e9f6b33 status: running warnings: - index: 0 code: years_band_ceiling message_he: '"5+ שנים" לא מגביל מלמעלה.' message_en: '"5+ years" sets no upper limit.' suggestion_he: null suggestion_en: null '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: '`job_not_found` or `user_not_found`' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '`requirements_rejected`; nothing was started.' content: application/json: schema: $ref: '#/components/schemas/RequirementsRejectedError' example: error: requirements_rejected message: One or more requirements cannot be used as written. rejected: - index: 3 code: too_many_musts message_he: אפשר לסמן עד 3 דרישות חובה. message_en: You can mark up to 3 requirements as must. suggestion_he: סמנו את הדרישה הזאת כ"יתרון". suggestion_en: Mark this requirement as nice-to-have. warnings: [] '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: Lang: name: x-vort-lang in: header required: false description: Language of notices and messages. Defaults to the partner default. schema: type: string enum: - he - en schemas: RunRequest: type: object required: - job_external_id - acting_user_external_id - target_count properties: job_external_id: type: string acting_user_external_id: type: string target_count: type: integer minimum: 1 requirements: type: array description: >- In display order; indexes are 0-based positions. At most 3 with kind `must`. When omitted, Vort derives requirements from the job description. items: $ref: '#/components/schemas/RequirementInput' RunAccepted: type: object required: - run_id - status - warnings properties: run_id: type: string format: uuid status: type: string const: running warnings: type: array items: $ref: '#/components/schemas/RequirementWarning' Error: type: object description: >- Error envelope. Branch on `error`; unknown codes are handled by HTTP status. required: - error - message properties: error: type: string examples: - invalid_partner_key - invalid_org_token - partner_disabled - organization_disabled - rate_limited - rate_limit_unavailable - code_not_found - code_expired - external_id_taken - invalid_user - job_not_found - user_not_found - run_not_found - candidate_not_in_run - invalid_decision message: type: string additionalProperties: true RequirementsRejectedError: allOf: - $ref: '#/components/schemas/Error' - type: object required: - rejected - warnings properties: error: const: requirements_rejected rejected: type: array items: $ref: '#/components/schemas/RequirementRejection' warnings: type: array items: $ref: '#/components/schemas/RequirementWarning' RequirementInput: type: object required: - text - kind properties: text: type: string kind: $ref: '#/components/schemas/RequirementKind' RequirementWarning: allOf: - $ref: '#/components/schemas/RequirementIssueBase' - type: object properties: code: type: string description: New codes may be added. examples: - short_term_may_be_dropped - years_band_ceiling - unverifiable_must RequirementRejection: allOf: - $ref: '#/components/schemas/RequirementIssueBase' - type: object properties: code: type: string description: New codes may be added. examples: - empty_text - invalid_kind - too_many_musts - duplicate - too_long - location_as_requirement RequirementKind: type: string enum: - must - nice RequirementIssueBase: type: object required: - index - code - message_he - message_en - suggestion_he - suggestion_en properties: index: type: integer minimum: 0 description: 0-based position in the submitted requirements array. code: type: string message_he: type: string message_en: type: string suggestion_he: type: - string - 'null' suggestion_en: type: - string - 'null' responses: Unauthorized: description: '`invalid_partner_key` or `invalid_org_token`' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_org_token message: The organization token is not valid. Forbidden: description: '`partner_disabled` or `organization_disabled`' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: organization_disabled message: This organization's Vort connection is disabled. RateLimited: description: '`rate_limited`' headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited message: Too many requests. ServiceUnavailable: description: >- `rate_limit_unavailable` — the rate limiter could not be checked, so the request was refused rather than let through unmetered. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limit_unavailable message: Rate limiting is temporarily unavailable. Retry shortly. headers: RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 securitySchemes: partnerKey: type: apiKey in: header name: x-partner-key description: 'Partner API key: `vpk_live_` + 48 lowercase hex. Server-side only.' orgToken: type: apiKey in: header name: x-vort-org description: >- Customer org token: `vot_` + 48 lowercase hex, from /activations/redeem. Server-side only. ````