{ "openapi": "3.1.0", "info": { "title": "Cenivoz API", "version": "2026-10-01", "description": "Connect your dealership system, ATS or HR platform to Cenivoz: push jobs and applicants, upload resumes, schedule AI-led interviews and receive the scored results.\n\n**Authentication.** OAuth 2.0 client credentials. Create a client ID and secret on the Developers page of the Cenivoz app, exchange them at `POST /oauth/token` for an access token (valid one hour), and send it as `Authorization: Bearer `. In this explorer, press **Authorize**.\n\n**Environments.** Sandbox (`https://connect-sandbox.cenivoz.com`) has its own data and simulates resume processing and interviews: no real calls, emails or AI. Production (`https://connect.cenivoz.com`) works on your real account. Each credential belongs to one environment. **Build and test against the sandbox.**\n\n**Pagination.** Lists return `{ data, hasMore, nextCursor }`; pass `nextCursor` as `?cursor=`.\n\n**Errors.** `{ \"error\": { \"code\", \"message\", \"details\", \"requestId\" } }`. Branch on `code`. The token endpoint uses the RFC 6749 format.\n\nGuides, webhooks and every error code: https://www.cenivoz.com/developers", "contact": { "name": "Cenivoz", "url": "https://www.cenivoz.com/developers" } }, "servers": [ { "url": "https://connect-sandbox.cenivoz.com", "description": "Sandbox (test data, simulated interviews)" }, { "url": "https://connect.cenivoz.com", "description": "Production" } ], "tags": [ { "name": "Authentication", "description": "Exchange your client ID and secret for an access token." }, { "name": "Account", "description": "Who you are." }, { "name": "Reference", "description": "What jobs and interviews can use: categories, questionnaires, languages." }, { "name": "Jobs", "description": "Your openings." }, { "name": "Applicants", "description": "People who applied, their resumes and cover letters." }, { "name": "Interviews", "description": "Scheduling, status, results, transcripts and recordings." }, { "name": "Statistics", "description": "Counts for a period." }, { "name": "Events and webhooks", "description": "What happened, and its delivery to your webhook endpoints." }, { "name": "Sandbox", "description": "Sandbox-only helpers to test outcomes on demand." } ], "paths": { "/oauth/token": { "post": { "operationId": "createAccessToken", "tags": [ "Authentication" ], "summary": "Get an access token", "description": "OAuth 2.0 client credentials. Send `grant_type=client_credentials` with your client ID and secret, either as HTTP Basic authentication or as `client_id` / `client_secret` in the body (form or JSON), not both. Optionally pass `scope` for a token that can do less. Cache the token: it is valid for an hour. Errors follow RFC 6749 (`{ \"error\": \"invalid_client\" }`).", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "grant_type": "client_credentials", "client_id": "cp_test_0a1b2c3d4e5f60718293a4b5", "client_secret": "cps_test_…" } } } }, "responses": { "200": { "description": "OK. The access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJjcF9saXZlXzViMWU5ZDBj...", "token_type": "Bearer", "expires_in": 3600, "scope": "jobs:read jobs:write applicants:read applicants:write interviews:read interviews:write stats:read events:read webhooks:read webhooks:write" } } } }, "400": { "description": "Bad request: `invalid_request`, `invalid_scope`, `unsupported_grant_type`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "invalid_request": { "summary": "Malformed token request", "value": { "error": "invalid_request", "error_description": "A parameter is missing, or credentials were sent both as Basic auth and in the body." } }, "invalid_scope": { "summary": "Scope not granted", "value": { "error": "invalid_scope", "error_description": "You asked for a scope your credential does not hold." } }, "unsupported_grant_type": { "summary": "Unsupported grant type", "value": { "error": "unsupported_grant_type", "error_description": "Only `client_credentials` is supported." } } } } } }, "401": { "description": "Unauthorized: `invalid_client`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "invalid_client": { "summary": "Client authentication failed", "value": { "error": "invalid_client", "error_description": "Wrong, unknown or revoked client id or secret (the same answer for all of these)." } } } } } }, "403": { "description": "Forbidden: `access_denied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "access_denied": { "summary": "Access is not allowed right now", "value": { "error": "access_denied", "error_description": "The company is suspended, API access is not enabled for this environment, or these credentials belong to the other environment (the message names the right URL)." } } } } } }, "429": { "description": "Too many requests: `too_many_requests`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "too_many_requests": { "summary": "Too many token requests", "value": { "error": "too_many_requests", "error_description": "Too many token requests from your address, or too many failed attempts for this client id. See `Retry-After`." } } } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Describe the credential", "description": "Which company, environment and scopes the access token belongs to. A good first call to check that authentication works.", "security": [ { "oauth2": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "clientId": "cp_live_5b1e9d0c7a3f42e8b6d1c093", "clientName": "DMS integration", "companyId": "company_a1b2c3d4e5f60718", "companyName": "Lone Star Motors", "environment": "production", "scopes": [ "jobs:read", "jobs:write", "applicants:read", "applicants:write", "interviews:read", "interviews:write", "stats:read", "events:read", "webhooks:read", "webhooks:write" ], "rateLimitPerMinute": 120, "apiVersion": "2026-10-01" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } } } }, "/v1/company": { "get": { "operationId": "getCompany", "tags": [ "Account" ], "summary": "Retrieve your company", "description": "Your company as Cenivoz knows it: name, interviewer name, default interview language.\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "example": { "id": "company_a1b2c3d4e5f60718", "object": "company", "name": "Lone Star Motors", "interviewerName": "Ava", "defaultInterviewLanguage": "en", "website": "https://lonestarmotors.example.com", "phone": "+15125550199", "email": "hiring@lonestarmotors.example.com" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" } }, "/v1/categories": { "get": { "operationId": "listCategories", "tags": [ "Reference" ], "summary": "List job categories", "description": "A job is created with one of these category ids. The category decides the interview style (the role playbook the interviewer follows).\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" }, "example": { "object": "list", "data": [ { "id": "cat_2b6d0e94a1f37c55", "object": "category", "name": "Lube Technician", "interviewRole": "Lube Technician" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" } }, "/v1/questionnaires": { "get": { "operationId": "listQuestionnaires", "tags": [ "Reference" ], "summary": "List screening questionnaires", "description": "Your company's screening questionnaires (created in the Cenivoz app). Attach them to a job with `screeningQuestionnaireIds`: the interview then asks these questions instead of its own technical and behavioral ones.\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireList" }, "example": { "object": "list", "data": [ { "id": "qnr_8c4e2a0f6b1d3957", "object": "questionnaire", "name": "Technician basics", "description": "Licence and availability", "questions": [ { "id": "q_1a2b3c4d5e6f7081", "text": "Do you have a valid driver licence?", "type": "yes_no", "expectedAnswer": "yes" }, { "id": "q_9f8e7d6c5b4a3921", "text": "Which shifts can you work?", "type": "open", "expectedAnswer": null } ], "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" } }, "/v1/interview-languages": { "get": { "operationId": "listInterviewLanguages", "tags": [ "Reference" ], "summary": "List interview languages", "description": "The languages your interviews can be held in (Cenivoz enables them per company), and whether each works for web and phone interviews. Pass a `code` as `language` when scheduling.\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewLanguageList" }, "example": { "object": "list", "data": [ { "code": "en", "name": "English", "nativeName": "English", "web": true, "phone": true, "isDefault": true }, { "code": "es", "name": "Spanish", "nativeName": "Español", "web": true, "phone": true, "isDefault": false } ] } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" } }, "/v1/jobs": { "post": { "operationId": "createJob", "tags": [ "Jobs" ], "summary": "Create a job", "description": "Creates an open job. `title` and `category` are required. Pass your own id as `externalId` to make retries safe and to find the job later by it.\n\nScope: `jobs:write`.", "security": [ { "oauth2": [ "jobs:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreate" }, "example": { "title": "Lube Technician", "category": "cat_0123456789abcdef", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "externalId": "ats-job-1042" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "open", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`, `duplicate_external_id`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "duplicate_external_id": { "summary": "duplicate_external_id: You already used this externalId", "value": { "error": { "code": "duplicate_external_id", "message": "You already used this externalId", "details": { "existingId": "job_7f3a91c2e4b05d18" }, "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:write" }, "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "summary": "List jobs", "description": "Newest first. Filter by status, category, title, your `externalId`, or `updatedSince` for incremental sync.\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only jobs with this status.", "schema": { "type": "string", "enum": [ "open", "filled", "closed" ] } }, { "name": "category", "in": "query", "required": false, "description": "Only jobs in this category id.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "search", "in": "query", "required": false, "description": "Only jobs whose title contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "externalId", "in": "query", "required": false, "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only jobs changed at or after this time (for incremental sync).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" }, "example": { "object": "list", "data": [ { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "open", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } ], "hasMore": true, "nextCursor": "eyJjIjoyMDUxMjU2NTMxMDAwLCJpIjoiNjU4ZjFhMmIzYzRkNWU2ZjcwODE5MmEzIn0" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" } }, "/v1/jobs/{jobId}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "Retrieve a job", "description": "`404 not_found` if the id does not exist in your company (in this environment).\n\nScope: `jobs:read`.", "security": [ { "oauth2": [ "jobs:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "open", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:read" }, "patch": { "operationId": "updateJob", "tags": [ "Jobs" ], "summary": "Update a job", "description": "Send only the fields to change. Set `status` to `closed` or `filled` to stop new applicants, or back to `open`.\n\nScope: `jobs:write`.", "security": [ { "oauth2": [ "jobs:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobUpdate" }, "example": { "status": "closed" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "open", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:write" } }, "/v1/applicants": { "post": { "operationId": "createApplicant", "tags": [ "Applicants" ], "summary": "Create an applicant", "description": "Adds an applicant to an open job. Cenivoz emails them nothing unless `sendWelcomeEmail` is `true`. Upload their resume next: an interview cannot be scheduled until it has been processed.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicantCreate" }, "example": { "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_0123456789abcdef", "source": "dealer-website", "externalId": "ats-cand-88231" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`, `duplicate_external_id`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "duplicate_external_id": { "summary": "duplicate_external_id: You already used this externalId", "value": { "error": { "code": "duplicate_external_id", "message": "You already used this externalId", "details": { "existingId": "job_7f3a91c2e4b05d18" }, "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" }, "get": { "operationId": "listApplicants", "tags": [ "Applicants" ], "summary": "List applicants", "description": "Newest first. Archived applicants are left out unless `archived=true`. Use `updatedSince` to pick up changes (status, resume processed, match score) since your last sync.\n\nScope: `applicants:read`.", "security": [ { "oauth2": [ "applicants:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "query", "required": false, "description": "Only applicants of this job.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Only applicants with this pipeline status.", "schema": { "type": "string", "enum": [ "new", "contacted", "interview_ready", "interviewed", "hired", "rejected" ] } }, { "name": "search", "in": "query", "required": false, "description": "Only applicants whose name, email or phone contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "archived", "in": "query", "required": false, "description": "`true` lists only archived applicants. The default lists only active ones.", "schema": { "type": "boolean" } }, { "name": "createdFrom", "in": "query", "required": false, "description": "Only applicants added on or after this date or time.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "createdTo", "in": "query", "required": false, "description": "Only applicants added before this date or time.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only applicants changed at or after this time (for incremental sync).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "externalId", "in": "query", "required": false, "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicantList" }, "example": { "object": "list", "data": [ { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:read" } }, "/v1/applicants/{applicantId}": { "get": { "operationId": "getApplicant", "tags": [ "Applicants" ], "summary": "Retrieve an applicant", "description": "Includes the profile read from the resume (skills, experience, education) and the cover letter text.\n\nScope: `applicants:read`.", "security": [ { "oauth2": [ "applicants:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:read" }, "patch": { "operationId": "updateApplicant", "tags": [ "Applicants" ], "summary": "Update an applicant", "description": "Send only the fields to change, including `status` (e.g. `hired`, `rejected`). Moving an applicant to another job requires that job to be open; the match score is then worked out again.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicantUpdate" }, "example": { "status": "hired" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" } }, "/v1/applicants/{applicantId}/archive": { "post": { "operationId": "archiveApplicant", "tags": [ "Applicants" ], "summary": "Archive an applicant", "description": "Hides the applicant from the default list and cancels their upcoming interviews. Reversible; repeating it changes nothing.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" } }, "/v1/applicants/{applicantId}/restore": { "post": { "operationId": "restoreApplicant", "tags": [ "Applicants" ], "summary": "Restore an applicant", "description": "Brings an archived applicant back. Interviews cancelled by archiving are not revived: schedule them again.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" } }, "/v1/applicants/{applicantId}/resume": { "post": { "operationId": "uploadResume", "tags": [ "Applicants" ], "summary": "Upload a resume", "description": "Either `multipart/form-data` with the file in the field `resume`, or JSON `{ \"fileName\", \"contentBase64\" }`. PDF, DOCX, DOC or TXT, up to 5 MB; the file's content must match its type. Returns 202: the resume is processed in the background (usually under a minute). Follow `GET /v1/applicants/{id}/resume-status`, or wait for `applicant.resume_parsed`. Processing fills the profile; it fills `email` and `phone` only if they were empty, and replaces `name` with the name in the resume. An earlier resume is kept in the applicant's history.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "resume" ], "properties": { "resume": { "type": "string", "format": "binary", "description": "The resume: PDF, DOCX, DOC or TXT, up to 5 MB. Its content must match its type." } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ResumeUploadJson" }, "example": { "fileName": "jordan-rivera.pdf", "contentBase64": "JVBERi0xLjQK..." } } } }, "responses": { "202": { "description": "Accepted.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeStatus" }, "example": { "applicantId": "cand_51c0a8e2d7f94b36", "status": "pending", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null, "matchStatus": "none" } } } }, "400": { "description": "Bad request: `invalid_json`, `invalid_request`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "invalid_request": { "summary": "invalid_request: The request is malformed", "value": { "error": { "code": "invalid_request", "message": "The request is malformed", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "413": { "description": "Payload too large: `payload_too_large`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "payload_too_large": { "summary": "payload_too_large: The request is too large", "value": { "error": { "code": "payload_too_large", "message": "The request is too large", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "415": { "description": "Unsupported media type: `unsupported_media_type`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unsupported_media_type": { "summary": "unsupported_media_type: Unsupported content type or file", "value": { "error": { "code": "unsupported_media_type", "message": "Unsupported content type or file", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "503": { "description": "Service unavailable: `queue_unavailable`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "queue_unavailable": { "summary": "queue_unavailable: A dependency is briefly unavailable", "value": { "error": { "code": "queue_unavailable", "message": "A dependency is briefly unavailable", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" } }, "/v1/applicants/{applicantId}/resume-status": { "get": { "operationId": "getResumeStatus", "tags": [ "Applicants" ], "summary": "Check resume processing", "description": "`pending` while it is being processed, `parsed` when done, `failed` if it could not be read.\n\nScope: `applicants:read`.", "security": [ { "oauth2": [ "applicants:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeStatus" }, "example": { "applicantId": "cand_51c0a8e2d7f94b36", "status": "pending", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null, "matchStatus": "none" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:read" } }, "/v1/applicants/{applicantId}/cover-letter": { "put": { "operationId": "setCoverLetter", "tags": [ "Applicants" ], "summary": "Set the cover letter", "description": "Saves the cover letter as text (it replaces an earlier one). The interviewer reads it before the interview, except in screening interviews.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverLetterText" }, "example": { "text": "Dear hiring team, I have four years of experience in a busy quick-lube bay..." } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" }, "delete": { "operationId": "deleteCoverLetter", "tags": [ "Applicants" ], "summary": "Remove the cover letter", "description": "Removes the applicant's cover letter. Repeating it changes nothing.\n\nScope: `applicants:write`.", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write" } }, "/v1/interviews": { "post": { "operationId": "scheduleInterview", "tags": [ "Interviews" ], "summary": "Schedule an interview", "description": "The applicant must have a processed resume. One interview takes place at a time per company: a clash returns `409 slot_taken`. A web interview returns `interviewUrl` (give it to the applicant, unless Cenivoz emails it: `notifyApplicant`). A phone interview calls the applicant at `scheduledAt` (or right away without it). Scheduling replaces the applicant's other interviews that have not started.\n\nScope: `interviews:write`.", "security": [ { "oauth2": [ "interviews:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewCreate" }, "example": { "applicantId": "cand_0123456789abcdef", "medium": "web", "scheduledAt": "2035-01-15T16:00:00Z", "language": "en", "notifyApplicant": true, "externalId": "ats-int-5521" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" }, "example": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "400": { "description": "Bad request: `invalid_json`, `phone_unavailable`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "phone_unavailable": { "summary": "phone_unavailable: Phone interviews are not available", "value": { "error": { "code": "phone_unavailable", "message": "Phone interviews are not available", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`, `slot_taken`, `resume_required`, `applicant_archived`, `phone_required`, `duplicate_external_id`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "slot_taken": { "summary": "slot_taken: Another interview occupies that time", "value": { "error": { "code": "slot_taken", "message": "Another interview occupies that time", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "resume_required": { "summary": "resume_required: The applicant has no processed resume", "value": { "error": { "code": "resume_required", "message": "The applicant has no processed resume", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "applicant_archived": { "summary": "applicant_archived: The applicant is archived", "value": { "error": { "code": "applicant_archived", "message": "The applicant is archived", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "phone_required": { "summary": "phone_required: The applicant has no phone number", "value": { "error": { "code": "phone_required", "message": "The applicant has no phone number", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "duplicate_external_id": { "summary": "duplicate_external_id: You already used this externalId", "value": { "error": { "code": "duplicate_external_id", "message": "You already used this externalId", "details": { "existingId": "job_7f3a91c2e4b05d18" }, "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:write" }, "get": { "operationId": "listInterviews", "tags": [ "Interviews" ], "summary": "List interviews", "description": "Newest first. Filter by status, job, applicant, dates, your `externalId`, or `updatedSince`.\n\nScope: `interviews:read`.", "security": [ { "oauth2": [ "interviews:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only interviews in this state. `awaiting_booking`: a scheduling link was sent and the applicant has not picked a time. `scheduled`: waiting to happen. `in_progress`: happening now. `completed`: ran to the end. `left_early`: the applicant ended it early or the connection dropped. `missed`: the time passed and the applicant never joined. `cancelled`: cancelled, or replaced by a newer interview for the same applicant. `error`: could not take place (for example a phone call that was not answered).", "schema": { "type": "string", "enum": [ "awaiting_booking", "scheduled", "in_progress", "completed", "left_early", "missed", "cancelled", "error" ] } }, { "name": "jobId", "in": "query", "required": false, "description": "Only interviews for this job.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "applicantId", "in": "query", "required": false, "description": "Only interviews of this applicant.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "createdFrom", "in": "query", "required": false, "description": "Only interviews created on or after this date or time.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "createdTo", "in": "query", "required": false, "description": "Only interviews created before this date or time.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only interviews changed at or after this time (for incremental sync).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "externalId", "in": "query", "required": false, "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewList" }, "example": { "object": "list", "data": [ { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:read" } }, "/v1/interviews/scheduling-link": { "post": { "operationId": "sendSchedulingLink", "tags": [ "Interviews" ], "summary": "Email a self-scheduling link", "description": "Cenivoz emails the applicant a link to pick their own time (a web interview). The interview is `awaiting_booking` until they do; then `interview.scheduled` follows. The applicant needs an email address and a processed resume.\n\nScope: `interviews:write`.", "security": [ { "oauth2": [ "interviews:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulingLinkCreate" }, "example": { "applicantId": "cand_0123456789abcdef" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" }, "example": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`, `resume_required`, `applicant_archived`, `email_required`, `duplicate_external_id`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "resume_required": { "summary": "resume_required: The applicant has no processed resume", "value": { "error": { "code": "resume_required", "message": "The applicant has no processed resume", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "applicant_archived": { "summary": "applicant_archived: The applicant is archived", "value": { "error": { "code": "applicant_archived", "message": "The applicant is archived", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "email_required": { "summary": "email_required: The applicant has no email address", "value": { "error": { "code": "email_required", "message": "The applicant has no email address", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "duplicate_external_id": { "summary": "duplicate_external_id: You already used this externalId", "value": { "error": { "code": "duplicate_external_id", "message": "You already used this externalId", "details": { "existingId": "job_7f3a91c2e4b05d18" }, "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:write" } }, "/v1/interviews/{interviewId}": { "get": { "operationId": "getInterview", "tags": [ "Interviews" ], "summary": "Retrieve an interview (status)", "description": "The interview and its `status`. Poll this, or listen for the `interview.*` events.\n\nScope: `interviews:read`.", "security": [ { "oauth2": [ "interviews:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" }, "example": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:read" } }, "/v1/interviews/{interviewId}/reschedule": { "post": { "operationId": "rescheduleInterview", "tags": [ "Interviews" ], "summary": "Reschedule an interview", "description": "Moves a scheduled interview that has not started to a new time (same link).\n\nScope: `interviews:write`.", "security": [ { "oauth2": [ "interviews:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1-200 letters, digits, `_ - : .`). Repeating the request with the same key returns the first response instead of doing the work again, for 24 hours. The same key with a different body is `422 idempotency_conflict`.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewReschedule" }, "example": { "scheduledAt": "2035-01-16T15:30:00Z" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" }, "example": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "400": { "description": "Bad request: `invalid_json`, `phone_unavailable`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "phone_unavailable": { "summary": "phone_unavailable: Phone interviews are not available", "value": { "error": { "code": "phone_unavailable", "message": "Phone interviews are not available", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `request_in_progress`, `slot_taken`, `invalid_state`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "request_in_progress: The same Idempotency-Key is still being processed", "value": { "error": { "code": "request_in_progress", "message": "The same Idempotency-Key is still being processed", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "slot_taken": { "summary": "slot_taken: Another interview occupies that time", "value": { "error": { "code": "slot_taken", "message": "Another interview occupies that time", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "invalid_state": { "summary": "invalid_state: Not possible in the record's current state", "value": { "error": { "code": "invalid_state", "message": "Not possible in the record's current state", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`, `idempotency_conflict`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } }, "idempotency_conflict": { "summary": "idempotency_conflict: The Idempotency-Key was used for a different request", "value": { "error": { "code": "idempotency_conflict", "message": "The Idempotency-Key was used for a different request", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:write" } }, "/v1/interviews/{interviewId}/cancel": { "post": { "operationId": "cancelInterview", "tags": [ "Interviews" ], "summary": "Cancel an interview", "description": "Only for an interview that has not started. The link stops working and a queued phone call is removed. Repeating it changes nothing.\n\nScope: `interviews:write`.", "security": [ { "oauth2": [ "interviews:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" }, "example": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `invalid_state`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "invalid_state: Not possible in the record's current state", "value": { "error": { "code": "invalid_state", "message": "Not possible in the record's current state", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:write" } }, "/v1/interviews/{interviewId}/result": { "get": { "operationId": "getInterviewResult", "tags": [ "Interviews" ], "summary": "Retrieve the result", "description": "Scores, recommendation, summary and screening answers. Scoring finishes shortly after the interview ends: while `scoringStatus` is `pending` there are no scores yet. The same JSON is pushed as `interview.completed`.\n\nScope: `interviews:read`.", "security": [ { "oauth2": [ "interviews:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewResult" }, "example": { "interviewId": "sess_m1x2k9_4c7e0a91f2d3", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "status": "completed", "completionType": "completed", "scoringStatus": "scored", "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "scores": { "overall": 81, "communication": 84, "technical": 77, "problemSolving": 79, "confidence": 80, "behavior": 86 }, "recommendation": "Hire", "summary": "Jordan described a methodical quick-lube routine, explained how they double-check drain plugs and filters, and handled the upset-customer scenario calmly.", "strengths": [ "Clear, step-by-step answers", "Safety-minded routine" ], "weaknesses": [ "Limited experience with tire balancing" ], "missingSkills": [ "Tire balancing" ], "recommendedTraining": [ "Wheel balancing and TPMS service" ], "screening": [ { "question": "Do you have a valid driver licence?", "type": "yes_no", "status": "answered", "answer": "yes", "expectedAnswer": "yes", "summary": "Yes, a Texas class C licence." } ], "externalId": "ats-int-5521" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:read" } }, "/v1/interviews/{interviewId}/transcript": { "get": { "operationId": "getInterviewTranscript", "tags": [ "Interviews" ], "summary": "Retrieve the transcript", "description": "What was said, turn by turn. `404 not_found` before the interview has taken place.\n\nScope: `interviews:read`.", "security": [ { "oauth2": [ "interviews:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" }, "example": { "interviewId": "sess_m1x2k9_4c7e0a91f2d3", "entries": [ { "speaker": "interviewer", "message": "Hi Jordan, thanks for joining. How are you doing today?", "elapsedMs": 0, "timestamp": "2035-01-15T16:00:41.000Z" }, { "speaker": "applicant", "message": "Doing well, thanks for having me.", "elapsedMs": 4200, "timestamp": "2035-01-15T16:00:45.000Z" } ] } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:read" } }, "/v1/interviews/{interviewId}/recording": { "get": { "operationId": "getInterviewRecording", "tags": [ "Interviews" ], "summary": "Get recording links", "description": "Temporary links (one hour) to the audio recording and any camera recordings. Ask again for fresh links; do not store or share them.\n\nScope: `interviews:read`.", "security": [ { "oauth2": [ "interviews:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" }, "example": { "interviewId": "sess_m1x2k9_4c7e0a91f2d3", "audioUrl": "https://api.example.com/api/interviews/sess_m1x2k9_4c7e0a91f2d3/audio?access=2051222400.Zm9vYmFy", "videoUrls": [], "expiresAt": "2035-01-15T17:13:19.000Z" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:read" } }, "/v1/stats/overview": { "get": { "operationId": "getStatsOverview", "tags": [ "Statistics" ], "summary": "Applicants and interviews for a period", "description": "How many applicants applied and how many interviews were conducted (default: the last 30 days, at most 366), optionally for one job.\n\nScope: `stats:read`.", "security": [ { "oauth2": [ "stats:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "The start of the period (inclusive). Default: 30 days before `to`.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "to", "in": "query", "required": false, "description": "The end of the period (exclusive). Default: now. The period may not be longer than 366 days.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "jobId", "in": "query", "required": false, "description": "Only this job (`GET /v1/stats/overview` only).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsOverview" }, "example": { "period": { "from": "2034-12-16T00:00:00.000Z", "to": "2035-01-15T00:00:00.000Z", "jobId": null }, "applicants": { "applied": 42, "byStatus": { "new": 9, "interview_ready": 6, "interviewed": 18, "hired": 4, "rejected": 5 }, "archived": 3 }, "interviews": { "scheduled": 31, "cancelled": 2, "conducted": { "started": 24, "completed": 21, "leftEarly": 3, "inProgress": 0, "averageScore": 72.400000000000005684341886080801486968994140625, "averageDurationSeconds": 701 } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "stats:read" } }, "/v1/stats/jobs": { "get": { "operationId": "getStatsJobs", "tags": [ "Statistics" ], "summary": "Statistics per job", "description": "Applicants and interviews per job for a period. Includes every open job, even without activity.\n\nScope: `stats:read`.", "security": [ { "oauth2": [ "stats:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "The start of the period (inclusive). Default: 30 days before `to`.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "to", "in": "query", "required": false, "description": "The end of the period (exclusive). Default: now. The period may not be longer than 366 days.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "jobId", "in": "query", "required": false, "description": "Only this job (`GET /v1/stats/overview` only).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsJobs" }, "example": { "period": { "from": "2034-12-16T00:00:00.000Z", "to": "2035-01-15T00:00:00.000Z", "jobId": null }, "data": [ { "jobId": "job_7f3a91c2e4b05d18", "title": "Lube Technician", "status": "open", "applicants": 17, "interviewsStarted": 11, "interviewsCompleted": 10, "averageScore": 74.099999999999994315658113919198513031005859375 } ] } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "stats:read" } }, "/v1/events": { "get": { "operationId": "listEvents", "tags": [ "Events and webhooks" ], "summary": "List events", "description": "Everything that happened in your account (the same events webhooks push), newest first, kept for 30 days. Use it to catch up after downtime, or instead of webhooks.\n\nScope: `events:read`.", "security": [ { "oauth2": [ "events:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Only events of this type.", "schema": { "type": "string", "enum": [ "job.created", "job.updated", "applicant.created", "applicant.updated", "applicant.status_changed", "applicant.resume_parsed", "applicant.resume_failed", "interview.invited", "interview.scheduled", "interview.started", "interview.completed", "interview.missed", "interview.cancelled", "interview.failed" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only events recorded at or after this time. Events are kept for 30 days.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "object": "list", "data": [ { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.created", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "none", "fileName": null, "uploadedAt": null, "error": null }, "match": { "status": "none", "score": null, "reasoning": null, "strengths": [], "gaps": [] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [], "certifications": [], "experience": [], "education": [] }, "coverLetterText": null } } } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "events:read" } }, "/v1/events/{eventId}": { "get": { "operationId": "getEvent", "tags": [ "Events and webhooks" ], "summary": "Retrieve an event", "description": "One event, exactly as it was pushed.\n\nScope: `events:read`.", "security": [ { "oauth2": [ "events:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "The event's `id` (`evt_…`).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.completed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "completed", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "completionType": "completed", "scoringStatus": "scored", "recordingConsent": { "givenAt": "2035-01-15T16:00:38.000Z", "scope": [ "audio", "video" ], "channel": "interview_page", "version": "2026-10-12" }, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T16:13:19.000Z" }, "result": { "interviewId": "sess_m1x2k9_4c7e0a91f2d3", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "status": "completed", "completionType": "completed", "scoringStatus": "scored", "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "scores": { "overall": 81, "communication": 84, "technical": 77, "problemSolving": 79, "confidence": 80, "behavior": 86 }, "recommendation": "Hire", "summary": "Jordan described a methodical quick-lube routine, explained how they double-check drain plugs and filters, and handled the upset-customer scenario calmly.", "strengths": [ "Clear, step-by-step answers", "Safety-minded routine" ], "weaknesses": [ "Limited experience with tire balancing" ], "missingSkills": [ "Tire balancing" ], "recommendedTraining": [ "Wheel balancing and TPMS service" ], "screening": [ { "question": "Do you have a valid driver licence?", "type": "yes_no", "status": "answered", "answer": "yes", "expectedAnswer": "yes", "summary": "Yes, a Texas class C licence." } ], "externalId": "ats-int-5521" } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "events:read" } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "tags": [ "Events and webhooks" ], "summary": "List webhook endpoints", "description": "Your webhook endpoints in this environment. Add and edit them (and see their signing secrets) on the Cenivoz Developers page.\n\nScope: `webhooks:read`.", "security": [ { "oauth2": [ "webhooks:read" ] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "data": [ { "id": "whe_3e8b2c1d9a7f6054", "object": "webhook_endpoint", "url": "https://hooks.lonestarmotors.example.com/cenivoz", "description": "DMS sync", "events": [], "status": "active", "disabledReason": null, "createdAt": "2035-01-15T15:02:11.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "webhooks:read" } }, "/v1/webhook-endpoints/{endpointId}/test": { "post": { "operationId": "testWebhookEndpoint", "tags": [ "Events and webhooks" ], "summary": "Send a test event", "description": "Queues a `webhook.test` event to the endpoint (tried once, whatever the endpoint's state).\n\nScope: `webhooks:write`.", "security": [ { "oauth2": [ "webhooks:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's `id` (`whe_…`).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "202": { "description": "Accepted.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEventResult" }, "example": { "queued": 1, "deliveries": [ { "id": "whd_1b3d5f7a9c0e2468", "object": "webhook_delivery", "eventId": "evt_0d9e1c7b5a3f2468", "endpointId": "whe_3e8b2c1d9a7f6054", "type": "webhook.test", "kind": "test", "status": "pending", "attemptCount": 0, "nextAttemptAt": "2035-01-15T15:02:14.000Z", "lastStatusCode": null, "lastError": null, "createdAt": "2035-01-15T15:02:14.000Z" } ] } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `no_endpoint`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_endpoint": { "summary": "no_endpoint: No webhook endpoint", "value": { "error": { "code": "no_endpoint", "message": "No webhook endpoint", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "webhooks:write" } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Events and webhooks" ], "summary": "List webhook deliveries", "description": "Delivery history for this environment, newest first, kept for 30 days.\n\nScope: `webhooks:read`.", "security": [ { "oauth2": [ "webhooks:read" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only deliveries with this status.", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "dead" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only deliveries of this event type, e.g. `interview.completed`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "endpointId", "in": "query", "required": false, "description": "Only deliveries to this endpoint.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size: 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" }, "example": { "object": "list", "data": [ { "id": "whd_6a0f4c2e8b1d3975", "object": "webhook_delivery", "eventId": "evt_0d9e1c7b5a3f2468", "endpointId": "whe_3e8b2c1d9a7f6054", "type": "interview.completed", "kind": "event", "status": "succeeded", "attemptCount": 1, "nextAttemptAt": null, "lastStatusCode": 200, "lastError": null, "createdAt": "2035-01-15T15:02:14.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "webhooks:read" } }, "/v1/webhook-deliveries/{deliveryId}/redeliver": { "post": { "operationId": "redeliverWebhook", "tags": [ "Events and webhooks" ], "summary": "Redeliver an event", "description": "Sends the same event to the same endpoint again (same event `id`, so your de-duplication still works).\n\nScope: `webhooks:write`.", "security": [ { "oauth2": [ "webhooks:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "description": "The delivery's `id` (`whd_…`).", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "202": { "description": "Accepted.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "example": { "id": "whd_6a0f4c2e8b1d3975", "object": "webhook_delivery", "eventId": "evt_0d9e1c7b5a3f2468", "endpointId": "whe_3e8b2c1d9a7f6054", "type": "interview.completed", "kind": "event", "status": "succeeded", "attemptCount": 1, "nextAttemptAt": null, "lastStatusCode": 200, "lastError": null, "createdAt": "2035-01-15T15:02:14.000Z" } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `no_endpoint`, `endpoint_disabled`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_endpoint": { "summary": "no_endpoint: No webhook endpoint", "value": { "error": { "code": "no_endpoint", "message": "No webhook endpoint", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "endpoint_disabled": { "summary": "endpoint_disabled: The webhook endpoint is switched off", "value": { "error": { "code": "endpoint_disabled", "message": "The webhook endpoint is switched off", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "webhooks:write" } }, "/v1/sandbox/interviews/{interviewId}/simulate": { "post": { "operationId": "simulateInterview", "tags": [ "Sandbox" ], "summary": "Simulate an interview (sandbox)", "description": "Plays the interview out now with the outcome you choose, and the matching events are sent. Sandbox interviews also run by themselves (see the sandbox guide); this is for testing a specific outcome on demand.\n\nScope: `interviews:write`. **Sandbox only.**", "security": [ { "oauth2": [ "interviews:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "interviewId", "in": "path", "required": true, "description": "The interview's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateInterview" }, "example": { "outcome": "completed", "overallScore": 82 } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResult" }, "example": { "simulated": true, "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "completed", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "completionType": "completed", "scoringStatus": "scored", "recordingConsent": { "givenAt": "2035-01-15T16:00:38.000Z", "scope": [ "audio", "video" ], "channel": "interview_page", "version": "2026-10-12" }, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T16:13:19.000Z" } } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`, `forbidden`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "forbidden": { "summary": "forbidden: Not allowed with this credential", "value": { "error": { "code": "forbidden", "message": "Not allowed with this credential", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `invalid_state`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "invalid_state: Not possible in the record's current state", "value": { "error": { "code": "invalid_state", "message": "Not possible in the record's current state", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "interviews:write", "x-sandbox-only": true } }, "/v1/sandbox/applicants/{applicantId}/resume/simulate": { "post": { "operationId": "simulateResume", "tags": [ "Sandbox" ], "summary": "Finish resume processing now (sandbox)", "description": "Finishes the processing of an uploaded resume at once, as `parsed` (with a sample profile) or `failed`.\n\nScope: `applicants:write`. **Sandbox only.**", "security": [ { "oauth2": [ "applicants:write" ] }, { "bearerAuth": [] } ], "parameters": [ { "name": "applicantId", "in": "path", "required": true, "description": "The applicant's `id`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResume" }, "example": { "outcome": "parsed" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Applicant" }, "example": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } }, "400": { "description": "Bad request: `invalid_json`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_json": { "summary": "invalid_json: The body is not valid JSON", "value": { "error": { "code": "invalid_json", "message": "The body is not valid JSON", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`, `forbidden`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "forbidden": { "summary": "forbidden: Not allowed with this credential", "value": { "error": { "code": "forbidden", "message": "Not allowed with this credential", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "404": { "description": "Not found: `not_found`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "not_found: No such record (or endpoint)", "value": { "error": { "code": "not_found", "message": "No such record (or endpoint)", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "409": { "description": "Conflict: `invalid_state`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "invalid_state: Not possible in the record's current state", "value": { "error": { "code": "invalid_state", "message": "Not possible in the record's current state", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "422": { "description": "Validation failed: `validation_failed`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_failed": { "summary": "validation_failed: A field is missing or invalid", "value": { "error": { "code": "validation_failed", "message": "A field is missing or invalid", "details": [ { "field": "title", "message": "is required" } ], "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "applicants:write", "x-sandbox-only": true } }, "/v1/sandbox/reset": { "post": { "operationId": "resetSandbox", "tags": [ "Sandbox" ], "summary": "Reset sandbox data", "description": "Deletes all of your company's sandbox jobs, applicants, interviews, events and deliveries. Sandbox credentials only.\n\nScope: `jobs:write`. **Sandbox only.**", "security": [ { "oauth2": [ "jobs:write" ] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxReset" }, "example": { "reset": true, "deleted": { "jobs": 3, "applicants": 12, "interviews": 9, "events": 57 } } } } }, "401": { "description": "Unauthorized: `unauthorized`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "unauthorized: Missing, invalid, expired or revoked access token", "value": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked access token", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "403": { "description": "Forbidden: `insufficient_scope`, `access_disabled`, `forbidden`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope: The credential lacks a required scope", "value": { "error": { "code": "insufficient_scope", "message": "The credential lacks a required scope", "details": { "requiredScope": "jobs:write" }, "requestId": "req_9c1e5f0a72d43b86e1" } } }, "access_disabled": { "summary": "access_disabled: API access is switched off for this environment", "value": { "error": { "code": "access_disabled", "message": "API access is switched off for this environment", "requestId": "req_9c1e5f0a72d43b86e1" } } }, "forbidden": { "summary": "forbidden: Not allowed with this credential", "value": { "error": { "code": "forbidden", "message": "Not allowed with this credential", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "429": { "description": "Too many requests: `rate_limited`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "rate_limited: Too many requests", "value": { "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } }, "500": { "description": "Internal error: `internal_error`. See the error reference.", "headers": { "X-Request-Id": { "description": "Identifies this request; the same value is `error.requestId` in errors. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per minute this credential may make.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the minute resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error: Something went wrong on our side", "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side", "requestId": "req_9c1e5f0a72d43b86e1" } } } } } } } }, "x-required-scope": "jobs:write", "x-sandbox-only": true } } }, "webhooks": { "job.created": { "post": { "summary": "job.created", "description": "A job was created (through the API or the app). `data.job`.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "job.created", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "job": { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "open", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "job.updated": { "post": { "summary": "job.updated", "description": "A job changed, including its status. `data.job` is the job after the change.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "job.updated", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "job": { "id": "job_7f3a91c2e4b05d18", "object": "job", "title": "Lube Technician", "description": "Perform oil changes, tire rotations and multi-point inspections in a busy quick-lube bay.", "department": "Service", "location": "Austin, TX", "employmentType": "full_time", "category": "cat_2b6d0e94a1f37c55", "categoryName": "Lube Technician", "salaryMin": 18, "salaryMax": 24, "salaryType": "hour", "requirements": "Valid driver licence. Six months of quick-lube experience preferred.", "shiftTiming": "Mon-Fri 7am-4pm, every other Saturday", "benefits": "Health, dental, 401(k) match, tool allowance", "applicationDeadline": null, "status": "closed", "critical": false, "screeningQuestionnaireIds": [], "externalId": "ats-job-1042", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "applicant.created": { "post": { "summary": "applicant.created", "description": "An applicant was added. `data.applicant`.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.created", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "none", "fileName": null, "uploadedAt": null, "error": null }, "match": { "status": "none", "score": null, "reasoning": null, "strengths": [], "gaps": [] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [], "certifications": [], "experience": [], "education": [] }, "coverLetterText": null } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "applicant.updated": { "post": { "summary": "applicant.updated", "description": "Anything about an applicant changed (also sent alongside the more specific events below). `data.applicant`.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.updated", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "applicant.status_changed": { "post": { "summary": "applicant.status_changed", "description": "The applicant's pipeline status changed (by your team, by you through the API, or automatically when an interview is scheduled or ends). `data.applicant.status` is the new status.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.status_changed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "interviewed", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "applicant.resume_parsed": { "post": { "summary": "applicant.resume_parsed", "description": "The resume was processed; `data.applicant.profile` is filled in. The pre-interview match follows shortly (`applicant.updated`).\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.resume_parsed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "parsed", "fileName": "jordan-rivera.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": null }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "applicant.resume_failed": { "post": { "summary": "applicant.resume_failed", "description": "The resume could not be read. `data.applicant.resume.error` says why. Upload another file.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "applicant.resume_failed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "applicant": { "id": "cand_51c0a8e2d7f94b36", "object": "applicant", "name": "Jordan Rivera", "email": "jordan.rivera@example.com", "phone": "+15125550100", "jobId": "job_7f3a91c2e4b05d18", "status": "new", "location": "Round Rock, TX", "linkedinUrl": "", "portfolioUrl": "", "expectedSalary": "$22/hour", "noticePeriod": "2 weeks", "source": "dealer-website", "tags": [], "resume": { "status": "failed", "fileName": "scan.pdf", "uploadedAt": "2035-01-15T15:02:11.000Z", "error": "The resume could not be read" }, "match": { "status": "scored", "score": 78, "reasoning": "Two years in a quick-lube bay and an ASE entry-level certification match the core of the role.", "strengths": [ "Quick-lube experience", "ASE G1 certified" ], "gaps": [ "No tire-balancing experience listed" ] }, "coverLetter": { "present": false, "source": null, "updatedAt": null }, "welcomeEmail": "none", "archivedAt": null, "externalId": "ats-cand-88231", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:14.000Z", "profile": { "skills": [ "Oil changes", "Tire rotation", "Multi-point inspection", "Customer service" ], "certifications": [ "ASE G1" ], "experience": [ { "company": "Speedy Lube", "title": "Lube Technician", "startDate": "2022-05", "endDate": "", "description": "Oil and filter changes, fluid top-ups, tire rotations." } ], "education": [ { "institution": "Austin Community College", "degree": "Certificate", "field": "Automotive Technology", "startDate": "2021-01", "endDate": "2022-05" } ] }, "coverLetterText": null } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.invited": { "post": { "summary": "interview.invited", "description": "A self-scheduling link was sent; the applicant has not picked a time yet.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.invited", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "awaiting_booking", "language": "en", "scheduledAt": null, "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.scheduled": { "post": { "summary": "interview.scheduled", "description": "An interview has a time (or a link that works now). Sent again when the time changes.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.scheduled", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "scheduled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.started": { "post": { "summary": "interview.started", "description": "The applicant joined (web) or answered the call (phone).\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.started", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "in_progress", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": "https://app.example.com/?code=sess_m1x2k9_4c7e0a91f2d3", "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.completed": { "post": { "summary": "interview.completed", "description": "The interview ended and its evaluation is final. `data.result` is the same as `GET /v1/interviews/{id}/result`; check `data.result.scoringStatus` (`scored`, `insufficient_data` or `failed`) and `data.interview.completionType`.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.completed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "completed", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "completionType": "completed", "scoringStatus": "scored", "recordingConsent": { "givenAt": "2035-01-15T16:00:38.000Z", "scope": [ "audio", "video" ], "channel": "interview_page", "version": "2026-10-12" }, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T16:13:19.000Z" }, "result": { "interviewId": "sess_m1x2k9_4c7e0a91f2d3", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "status": "completed", "completionType": "completed", "scoringStatus": "scored", "startedAt": "2035-01-15T16:00:41.000Z", "endedAt": "2035-01-15T16:13:05.000Z", "durationSeconds": 744, "scores": { "overall": 81, "communication": 84, "technical": 77, "problemSolving": 79, "confidence": 80, "behavior": 86 }, "recommendation": "Hire", "summary": "Jordan described a methodical quick-lube routine, explained how they double-check drain plugs and filters, and handled the upset-customer scenario calmly.", "strengths": [ "Clear, step-by-step answers", "Safety-minded routine" ], "weaknesses": [ "Limited experience with tire balancing" ], "missingSkills": [ "Tire balancing" ], "recommendedTraining": [ "Wheel balancing and TPMS service" ], "screening": [ { "question": "Do you have a valid driver licence?", "type": "yes_no", "status": "answered", "answer": "yes", "expectedAnswer": "yes", "summary": "Yes, a Texas class C licence." } ], "externalId": "ats-int-5521" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.missed": { "post": { "summary": "interview.missed", "description": "The time passed (by more than the 30-minute join window) and the applicant never joined. The link no longer works; schedule a new interview to try again.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.missed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "missed", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.cancelled": { "post": { "summary": "interview.cancelled", "description": "The interview was cancelled, or replaced by a newer interview for the same applicant.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.cancelled", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "web", "status": "cancelled", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" } } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "interview.failed": { "post": { "summary": "interview.failed", "description": "The interview could not take place (for example a phone call that was not answered). `data.reason` explains.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "interview.failed", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "interview": { "id": "sess_m1x2k9_4c7e0a91f2d3", "object": "interview", "applicantId": "cand_51c0a8e2d7f94b36", "jobId": "job_7f3a91c2e4b05d18", "medium": "phone", "status": "error", "language": "en", "scheduledAt": "2035-01-15T16:00:00.000Z", "timezone": "UTC", "videoRequired": false, "plannedDurationMinutes": 15, "startedAt": null, "endedAt": null, "durationSeconds": null, "completionType": null, "scoringStatus": "pending", "recordingConsent": null, "interviewUrl": null, "externalId": "ats-int-5521", "createdAt": "2035-01-15T15:02:11.000Z", "updatedAt": "2035-01-15T15:02:11.000Z" }, "reason": "The call was not answered" } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } }, "webhook.test": { "post": { "summary": "webhook.test", "description": "A test event you asked for. Not related to any record.\n\nVerify the `Cenivoz-Signature` header, answer 2xx within 10 seconds, and de-duplicate on the event `id`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_0d9e1c7b5a3f2468", "object": "event", "type": "webhook.test", "apiVersion": "2026-10-01", "environment": "production", "createdAt": "2035-01-15T15:02:14.000Z", "data": { "message": "This is a test event from Cenivoz. If you can read it, your endpoint works.", "endpointId": "whe_3e8b2c1d9a7f6054" } } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered; anything else is retried." } } } } }, "components": { "schemas": { "JobCreate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "The job title, e.g. \"Lube Technician\".", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "description": "What the job involves. The interviewer uses it to answer the applicant's questions.", "maxLength": 20000 }, "department": { "type": "string", "description": "The department, e.g. \"Service\".", "maxLength": 200 }, "location": { "type": "string", "description": "Where the job is, e.g. \"Austin, TX\".", "maxLength": 200 }, "employmentType": { "type": "string", "description": "`full_time` (default), `part_time`, `contract` or `intern`.", "enum": [ "full_time", "part_time", "contract", "intern" ] }, "category": { "type": "string", "description": "The job category: an `id` from `GET /v1/categories`. It decides the interview style (the role playbook the interviewer follows). Required when creating.", "minLength": 1, "maxLength": 100 }, "salaryMin": { "type": "number", "description": "The lower end of the pay range, in the unit given by `salaryType`. The interviewer never discusses pay; this is for your records.", "minimum": 0, "maximum": 100000000 }, "salaryMax": { "type": "number", "description": "The upper end of the pay range. Must not be less than `salaryMin`.", "minimum": 0, "maximum": 100000000 }, "salaryType": { "type": "string", "description": "What the salary figures are per: `hour`, `week`, `month` or `year` (default).", "enum": [ "hour", "week", "month", "year" ] }, "requirements": { "type": "string", "description": "What the applicant needs: skills, licences, experience.", "maxLength": 20000 }, "shiftTiming": { "type": "string", "description": "The working hours or shifts, e.g. \"Mon-Fri 8am-5pm\".", "maxLength": 500 }, "benefits": { "type": "string", "description": "Benefits offered.", "maxLength": 5000 }, "applicationDeadline": { "anyOf": [ { "description": "The last moment applicants can be added: a date (`2035-12-31`) or a timestamp. After it, adding an applicant to the job fails. `null` removes it.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, { "type": "null" } ] }, "critical": { "type": "boolean", "description": "Marks the job as a priority opening." }, "screeningQuestionnaireIds": { "type": "array", "description": "Screening questionnaires to attach (ids from `GET /v1/questionnaires`, at most 10). When a job has questionnaires, the interview asks the company's questions instead of its own technical and behavioral questions. Send `[]` to remove them.", "items": { "type": "string", "description": "A questionnaire id.", "minLength": 1, "maxLength": 100 }, "maxItems": 10 }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 } }, "required": [ "title", "category" ] }, "JobUpdate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "The job title, e.g. \"Lube Technician\".", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "description": "What the job involves. The interviewer uses it to answer the applicant's questions.", "maxLength": 20000 }, "department": { "type": "string", "description": "The department, e.g. \"Service\".", "maxLength": 200 }, "location": { "type": "string", "description": "Where the job is, e.g. \"Austin, TX\".", "maxLength": 200 }, "employmentType": { "type": "string", "description": "`full_time` (default), `part_time`, `contract` or `intern`.", "enum": [ "full_time", "part_time", "contract", "intern" ] }, "category": { "type": "string", "description": "The job category: an `id` from `GET /v1/categories`. It decides the interview style (the role playbook the interviewer follows). Required when creating.", "minLength": 1, "maxLength": 100 }, "salaryMin": { "type": "number", "description": "The lower end of the pay range, in the unit given by `salaryType`. The interviewer never discusses pay; this is for your records.", "minimum": 0, "maximum": 100000000 }, "salaryMax": { "type": "number", "description": "The upper end of the pay range. Must not be less than `salaryMin`.", "minimum": 0, "maximum": 100000000 }, "salaryType": { "type": "string", "description": "What the salary figures are per: `hour`, `week`, `month` or `year` (default).", "enum": [ "hour", "week", "month", "year" ] }, "requirements": { "type": "string", "description": "What the applicant needs: skills, licences, experience.", "maxLength": 20000 }, "shiftTiming": { "type": "string", "description": "The working hours or shifts, e.g. \"Mon-Fri 8am-5pm\".", "maxLength": 500 }, "benefits": { "type": "string", "description": "Benefits offered.", "maxLength": 5000 }, "applicationDeadline": { "anyOf": [ { "description": "The last moment applicants can be added: a date (`2035-12-31`) or a timestamp. After it, adding an applicant to the job fails. `null` removes it.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, { "type": "null" } ] }, "critical": { "type": "boolean", "description": "Marks the job as a priority opening." }, "screeningQuestionnaireIds": { "type": "array", "description": "Screening questionnaires to attach (ids from `GET /v1/questionnaires`, at most 10). When a job has questionnaires, the interview asks the company's questions instead of its own technical and behavioral questions. Send `[]` to remove them.", "items": { "type": "string", "description": "A questionnaire id.", "minLength": 1, "maxLength": 100 }, "maxItems": 10 }, "status": { "type": "string", "description": "Change the job's status. `open`: accepting applicants. `closed`: not accepting applicants. `filled`: closed because someone was hired.", "enum": [ "open", "filled", "closed" ] } }, "minProperties": 1 }, "JobListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Only jobs with this status.", "enum": [ "open", "filled", "closed" ] }, "category": { "type": "string", "description": "Only jobs in this category id.", "minLength": 1, "maxLength": 100 }, "search": { "type": "string", "description": "Only jobs whose title contains this text (case-insensitive).", "minLength": 1, "maxLength": 100 }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 }, "updatedSince": { "description": "Only jobs changed at or after this time (for incremental sync).", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "JobIdParams": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "description": "The job's `id`.", "minLength": 1, "maxLength": 100 } }, "required": [ "jobId" ] }, "PageQuery": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "ApplicantCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The applicant's full name. Required when creating. Note: once the resume has been processed, the name found in the resume replaces this one.", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "description": "The applicant's email address. Needed for scheduling links and emailed invitations.", "format": "email", "maxLength": 254 }, "phone": { "type": "string", "description": "The applicant's phone number in international format (`+15125550100`). Required for phone interviews.", "maxLength": 40 }, "jobId": { "type": "string", "description": "The job the person applied for: a job `id`. The job must be `open` and not past its deadline. Required when creating.", "minLength": 1, "maxLength": 100 }, "location": { "type": "string", "description": "Where the applicant lives.", "maxLength": 200 }, "linkedinUrl": { "type": "string", "description": "A link to their LinkedIn profile (http or https).", "format": "uri", "maxLength": 500 }, "portfolioUrl": { "type": "string", "description": "A link to their portfolio or website (http or https).", "format": "uri", "maxLength": 500 }, "expectedSalary": { "type": "string", "description": "What they are asking for, as free text.", "maxLength": 100 }, "noticePeriod": { "type": "string", "description": "How soon they could start, as free text, e.g. \"2 weeks\".", "maxLength": 100 }, "source": { "type": "string", "description": "Where the applicant came from (a free label). Defaults to `api`.", "minLength": 1, "maxLength": 100 }, "tags": { "type": "array", "description": "Free labels, up to 30. In the sandbox, `sim:resume-fail`, `sim:left-early`, `sim:missed`, `sim:error` and `sim:manual` control the simulation (see the sandbox guide).", "items": { "type": "string", "description": "A tag.", "minLength": 1, "maxLength": 50 }, "maxItems": 30 }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 }, "sendWelcomeEmail": { "type": "boolean", "description": "`true` makes Cenivoz email the applicant its standard welcome message with a link to book their interview, as soon as their resume has been processed (the same email the app sends). Default `false`: Cenivoz sends nothing and you decide when to invite them." } }, "required": [ "name", "jobId" ] }, "ApplicantUpdate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The applicant's full name. Required when creating. Note: once the resume has been processed, the name found in the resume replaces this one.", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "description": "The applicant's email address. Needed for scheduling links and emailed invitations.", "format": "email", "maxLength": 254 }, "phone": { "type": "string", "description": "The applicant's phone number in international format (`+15125550100`). Required for phone interviews.", "maxLength": 40 }, "jobId": { "type": "string", "description": "The job the person applied for: a job `id`. The job must be `open` and not past its deadline. Required when creating.", "minLength": 1, "maxLength": 100 }, "location": { "type": "string", "description": "Where the applicant lives.", "maxLength": 200 }, "linkedinUrl": { "type": "string", "description": "A link to their LinkedIn profile (http or https).", "format": "uri", "maxLength": 500 }, "portfolioUrl": { "type": "string", "description": "A link to their portfolio or website (http or https).", "format": "uri", "maxLength": 500 }, "expectedSalary": { "type": "string", "description": "What they are asking for, as free text.", "maxLength": 100 }, "noticePeriod": { "type": "string", "description": "How soon they could start, as free text, e.g. \"2 weeks\".", "maxLength": 100 }, "source": { "type": "string", "description": "Where the applicant came from (a free label). Defaults to `api`.", "minLength": 1, "maxLength": 100 }, "tags": { "type": "array", "description": "Free labels, up to 30. In the sandbox, `sim:resume-fail`, `sim:left-early`, `sim:missed`, `sim:error` and `sim:manual` control the simulation (see the sandbox guide).", "items": { "type": "string", "description": "A tag.", "minLength": 1, "maxLength": 50 }, "maxItems": 30 }, "status": { "type": "string", "description": "Move the applicant along your pipeline. Where the applicant is in your pipeline: `new`, `contacted`, `interview_ready` (an interview was scheduled or a scheduling link sent), `interviewed` (an interview took place), `hired`, `rejected`. Cenivoz moves an applicant forward automatically when an interview is scheduled and when it ends, but never backwards and never over `hired` / `rejected`.", "enum": [ "new", "contacted", "interview_ready", "interviewed", "hired", "rejected" ] } }, "minProperties": 1 }, "ApplicantListQuery": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "description": "Only applicants of this job.", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "description": "Only applicants with this pipeline status.", "enum": [ "new", "contacted", "interview_ready", "interviewed", "hired", "rejected" ] }, "search": { "type": "string", "description": "Only applicants whose name, email or phone contains this text (case-insensitive).", "minLength": 1, "maxLength": 100 }, "archived": { "type": "boolean", "description": "`true` lists only archived applicants. The default lists only active ones." }, "createdFrom": { "description": "Only applicants added on or after this date or time.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "createdTo": { "description": "Only applicants added before this date or time.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "updatedSince": { "description": "Only applicants changed at or after this time (for incremental sync).", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 }, "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "ApplicantIdParams": { "type": "object", "additionalProperties": false, "properties": { "applicantId": { "type": "string", "description": "The applicant's `id`.", "minLength": 1, "maxLength": 100 } }, "required": [ "applicantId" ] }, "ResumeUploadJson": { "type": "object", "additionalProperties": false, "properties": { "fileName": { "type": "string", "description": "The file name, with its extension (`.pdf`, `.docx`, `.doc` or `.txt`).", "minLength": 1, "maxLength": 200 }, "contentBase64": { "type": "string", "description": "The file's bytes, base64-encoded. At most 5 MB before encoding.", "minLength": 1, "maxLength": 7340036 } }, "required": [ "fileName", "contentBase64" ] }, "CoverLetterText": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "description": "The cover letter as plain text, up to 8,000 characters. The interviewer reads it (except in screening interviews). It replaces any earlier cover letter.", "minLength": 1, "maxLength": 8000 } }, "required": [ "text" ] }, "InterviewCreate": { "type": "object", "additionalProperties": false, "properties": { "applicantId": { "type": "string", "description": "The applicant to interview: an applicant `id`. They must not be archived and must have a processed resume.", "minLength": 1, "maxLength": 100 }, "medium": { "type": "string", "description": "`web`: the applicant opens a link (`interviewUrl`) in their browser. `phone`: the interviewer calls them at the given time (needs the applicant's `phone`).", "enum": [ "web", "phone" ] }, "scheduledAt": { "type": "string", "format": "date-time", "description": "When the interview takes place, as a UTC timestamp on a 15-minute mark (`09:00`, `09:15`, ...). Optional for `web` (without it the link works right away); for `phone`, omitting it places the call immediately." }, "videoRequired": { "type": "boolean", "description": "Ask the applicant for their camera (`web` only). The interviewer stays audio-only; this decides whether video is recorded." }, "language": { "type": "string", "description": "The interview language: a `code` from `GET /v1/interview-languages`. Default: your company's default language.", "minLength": 1, "maxLength": 10 }, "notifyApplicant": { "type": "boolean", "description": "`true` (default) lets Cenivoz email the applicant the interview time and link (for a `web` interview with `scheduledAt`) and send its reminder 15 minutes before. `false`: Cenivoz sends the applicant nothing and you send `interviewUrl` yourself." }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 } }, "required": [ "applicantId", "medium" ] }, "SchedulingLinkCreate": { "type": "object", "additionalProperties": false, "properties": { "applicantId": { "type": "string", "description": "The applicant to invite. They need an email address and a processed resume.", "minLength": 1, "maxLength": 100 }, "language": { "type": "string", "description": "The interview language: a `code` from `GET /v1/interview-languages`. Default: your company's default language.", "minLength": 1, "maxLength": 10 }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 } }, "required": [ "applicantId" ] }, "InterviewReschedule": { "type": "object", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date-time", "description": "The new time: a UTC timestamp on a 15-minute mark (and in the future for a phone interview)." }, "notifyApplicant": { "type": "boolean", "description": "`true` (default) emails the applicant the new time. `false` sends nothing." } }, "required": [ "scheduledAt" ] }, "InterviewListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Only interviews in this state. `awaiting_booking`: a scheduling link was sent and the applicant has not picked a time. `scheduled`: waiting to happen. `in_progress`: happening now. `completed`: ran to the end. `left_early`: the applicant ended it early or the connection dropped. `missed`: the time passed and the applicant never joined. `cancelled`: cancelled, or replaced by a newer interview for the same applicant. `error`: could not take place (for example a phone call that was not answered).", "enum": [ "awaiting_booking", "scheduled", "in_progress", "completed", "left_early", "missed", "cancelled", "error" ] }, "jobId": { "type": "string", "description": "Only interviews for this job.", "minLength": 1, "maxLength": 100 }, "applicantId": { "type": "string", "description": "Only interviews of this applicant.", "minLength": 1, "maxLength": 100 }, "createdFrom": { "description": "Only interviews created on or after this date or time.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "createdTo": { "description": "Only interviews created before this date or time.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "updatedSince": { "description": "Only interviews changed at or after this time (for incremental sync).", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "externalId": { "type": "string", "description": "Your own identifier for this record (for example the id in your ATS or DMS), up to 100 characters. Unique per record type within your company and environment: a second create with the same value fails with `409 duplicate_external_id` (naming the existing record) instead of making a duplicate. Look records up with `?externalId=`.", "minLength": 1, "maxLength": 100 }, "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "InterviewIdParams": { "type": "object", "additionalProperties": false, "properties": { "interviewId": { "type": "string", "description": "The interview's `id`.", "minLength": 1, "maxLength": 100 } }, "required": [ "interviewId" ] }, "StatsQuery": { "type": "object", "additionalProperties": false, "properties": { "from": { "description": "The start of the period (inclusive). Default: 30 days before `to`.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "to": { "description": "The end of the period (exclusive). Default: now. The period may not be longer than 366 days.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "jobId": { "type": "string", "description": "Only this job (`GET /v1/stats/overview` only).", "minLength": 1, "maxLength": 100 } } }, "EventListQuery": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "Only events of this type.", "enum": [ "job.created", "job.updated", "applicant.created", "applicant.updated", "applicant.status_changed", "applicant.resume_parsed", "applicant.resume_failed", "interview.invited", "interview.scheduled", "interview.started", "interview.completed", "interview.missed", "interview.cancelled", "interview.failed" ] }, "since": { "description": "Only events recorded at or after this time. Events are kept for 30 days.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "EventIdParams": { "type": "object", "additionalProperties": false, "properties": { "eventId": { "type": "string", "description": "The event's `id` (`evt_…`).", "minLength": 1, "maxLength": 100 } }, "required": [ "eventId" ] }, "DeliveryListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Only deliveries with this status.", "enum": [ "pending", "succeeded", "failed", "dead" ] }, "type": { "type": "string", "description": "Only deliveries of this event type, e.g. `interview.completed`.", "minLength": 1, "maxLength": 100 }, "endpointId": { "type": "string", "description": "Only deliveries to this endpoint.", "minLength": 1, "maxLength": 100 }, "limit": { "type": "integer", "description": "Page size: 1 to 100. Default 25.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "The `nextCursor` of the previous page. Opaque: pass it back unchanged.", "maxLength": 300 } } }, "DeliveryIdParams": { "type": "object", "additionalProperties": false, "properties": { "deliveryId": { "type": "string", "description": "The delivery's `id` (`whd_…`).", "minLength": 1, "maxLength": 100 } }, "required": [ "deliveryId" ] }, "EndpointIdParams": { "type": "object", "additionalProperties": false, "properties": { "endpointId": { "type": "string", "description": "The endpoint's `id` (`whe_…`).", "minLength": 1, "maxLength": 100 } }, "required": [ "endpointId" ] }, "SimulateInterview": { "type": "object", "additionalProperties": false, "properties": { "outcome": { "type": "string", "description": "What happens: `completed` (ran to the end and is scored), `left_early` (the applicant left after a minute; no scores), `missed` (the applicant never joined) or `failed` (the call could not take place). Default `completed`.", "enum": [ "completed", "left_early", "missed", "failed" ] }, "overallScore": { "type": "integer", "description": "For `completed`: the overall score to give (0-100). Default: a fixed pseudo-random score derived from the interview id.", "minimum": 0, "maximum": 100 } } }, "SimulateResume": { "type": "object", "additionalProperties": false, "properties": { "outcome": { "type": "string", "description": "`parsed` (default): the resume is read and the profile filled with sample content. `failed`: it could not be read.", "enum": [ "parsed", "failed" ] } } }, "ErrorResponse": { "type": "object", "description": "Every error response has this shape (except `POST /oauth/token`, which follows RFC 6749).", "properties": { "error": { "type": "object", "description": "What went wrong.", "properties": { "code": { "type": "string", "description": "A stable, machine-readable code. Branch on this. The error reference lists every code." }, "message": { "type": "string", "description": "A sentence for humans. The wording may improve over time: do not parse it." }, "details": { "description": "More detail, when there is any. For `validation_failed` an array of `{ \"field\", \"message\" }`. For `insufficient_scope` `{ \"requiredScope\" }`. For `duplicate_external_id` `{ \"existingId\" }`. For `unsupported_media_type` on a resume `{ \"allowed\" }`. Absent otherwise." }, "requestId": { "type": "string", "description": "Identifies this request in our logs (also the `X-Request-Id` header). Quote it when you contact support." } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] }, "ValidationDetail": { "type": "object", "description": "One problem found by validation.", "properties": { "field": { "type": "string", "description": "The property the problem is about, in dot notation (`salaryMin`, `tags.2`), or `(body)` for the body as a whole." }, "message": { "type": "string", "description": "What is wrong with it." } }, "required": [ "field", "message" ] }, "TokenRequest": { "type": "object", "description": "Send as `application/x-www-form-urlencoded` (standard) or JSON.", "properties": { "grant_type": { "type": "string", "description": "Always `client_credentials`.", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Your client ID (`cp_live_…` or `cp_test_…`). Send it and the secret here, or use HTTP Basic authentication instead: not both." }, "client_secret": { "type": "string", "description": "Your client secret (`cps_live_…` or `cps_test_…`)." }, "scope": { "type": "string", "description": "Optional. A space-separated subset of the scopes your credential holds, to get a token that can do less. Default: all of them." } }, "required": [ "grant_type" ] }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The token. Send it as `Authorization: Bearer `. Treat it as opaque." }, "token_type": { "type": "string", "description": "Always `Bearer`.", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds until the token expires (3600: one hour). Reuse it until then." }, "scope": { "type": "string", "description": "The scopes the token carries, space-separated." } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "OAuthError": { "type": "object", "description": "Errors of `POST /oauth/token` follow RFC 6749 and are NOT in the usual error envelope.", "properties": { "error": { "type": "string", "description": "An OAuth error code: `invalid_request`, `invalid_client`, `unsupported_grant_type`, `invalid_scope`, `access_denied` or `too_many_requests`." }, "error_description": { "type": "string", "description": "A sentence for humans." } }, "required": [ "error", "error_description" ] }, "Me": { "type": "object", "description": "Who you are.", "properties": { "clientId": { "type": "string", "description": "The client ID this token was issued to." }, "clientName": { "type": "string", "description": "The name you gave the credential." }, "companyId": { "type": "string", "description": "Your company's id in Cenivoz." }, "companyName": { "type": "string", "description": "Your company's name." }, "environment": { "type": "string", "description": "`sandbox` or `production`: decided by the credential.", "enum": [ "sandbox", "production" ] }, "scopes": { "type": "array", "description": "The scopes this token holds right now (a token can hold fewer than its credential).", "items": { "type": "string" } }, "rateLimitPerMinute": { "type": "integer", "description": "How many requests per minute this credential may make." }, "apiVersion": { "type": "string", "description": "The API version (dated). Breaking changes would come under a new `/v2` path." } }, "required": [ "clientId", "clientName", "companyId", "companyName", "environment", "scopes", "rateLimitPerMinute", "apiVersion" ] }, "Company": { "type": "object", "description": "Your company as Cenivoz knows it.", "properties": { "id": { "type": "string", "description": "Your company's id." }, "object": { "type": "string", "description": "Always `company`.", "enum": [ "company" ] }, "name": { "type": "string", "description": "The company name." }, "interviewerName": { "type": "string", "description": "The name the interviewer introduces itself with." }, "defaultInterviewLanguage": { "type": "string", "description": "The default interview language code." }, "website": { "type": "string", "description": "The company website. Empty string if none." }, "phone": { "type": "string", "description": "The company phone. Empty string if none." }, "email": { "type": "string", "description": "The company email. Empty string if none." } }, "required": [ "id", "object", "name", "interviewerName", "defaultInterviewLanguage", "website", "phone", "email" ] }, "Category": { "type": "object", "description": "A job category.", "properties": { "id": { "type": "string", "description": "The category id. Use it as `category` when creating a job." }, "object": { "type": "string", "description": "Always `category`.", "enum": [ "category" ] }, "name": { "type": "string", "description": "The category's name, e.g. \"Service Technician\"." }, "interviewRole": { "type": [ "string", "null" ], "description": "The interview playbook used for jobs in this category, or `null` if the general one is used." } }, "required": [ "id", "object", "name", "interviewRole" ] }, "QuestionnaireQuestion": { "type": "object", "description": "One screening question.", "properties": { "id": { "type": "string", "description": "The question id." }, "text": { "type": "string", "description": "The question as the interviewer asks it." }, "type": { "type": "string", "description": "`open` (free answer) or `yes_no` (has a required answer).", "enum": [ "open", "yes_no" ] }, "expectedAnswer": { "type": [ "string", "null" ], "description": "For `yes_no`: the answer the job needs.", "enum": [ "yes", "no", null ] } }, "required": [ "id", "text", "type", "expectedAnswer" ] }, "Questionnaire": { "type": "object", "description": "A screening questionnaire (managed in the Cenivoz app).", "properties": { "id": { "type": "string", "description": "The questionnaire id. Attach it to a job with `screeningQuestionnaireIds`." }, "object": { "type": "string", "description": "Always `questionnaire`.", "enum": [ "questionnaire" ] }, "name": { "type": "string", "description": "The questionnaire's name." }, "description": { "type": "string", "description": "What it is for. Empty string if none." }, "questions": { "type": "array", "description": "The questions, in the order they are asked.", "items": { "$ref": "#/components/schemas/QuestionnaireQuestion" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last changed." } }, "required": [ "id", "object", "name", "description", "questions", "createdAt", "updatedAt" ] }, "InterviewLanguage": { "type": "object", "description": "A language your interviews can be held in.", "properties": { "code": { "type": "string", "description": "The language code to send as `language`." }, "name": { "type": "string", "description": "The language in English, e.g. \"Spanish\"." }, "nativeName": { "type": "string", "description": "The language in itself, e.g. \"Español\"." }, "web": { "type": "boolean", "description": "Whether web interviews can be held in it." }, "phone": { "type": "boolean", "description": "Whether phone interviews can be held in it." }, "isDefault": { "type": "boolean", "description": "Whether it is your company's default." } }, "required": [ "code", "name", "nativeName", "web", "phone", "isDefault" ] }, "InterviewLanguageList": { "type": "object", "description": "The interview languages available to you.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The languages Cenivoz has enabled for your company.", "items": { "$ref": "#/components/schemas/InterviewLanguage" } } }, "required": [ "object", "data" ] }, "Job": { "type": "object", "description": "A job opening.", "properties": { "id": { "type": "string", "description": "The job's id (`job_…`)." }, "object": { "type": "string", "description": "Always `job`.", "enum": [ "job" ] }, "title": { "type": "string", "description": "The job title." }, "description": { "type": "string", "description": "What the job involves. Empty string if none." }, "department": { "type": "string", "description": "The department. Empty string if none." }, "location": { "type": "string", "description": "Where the job is. Empty string if none." }, "employmentType": { "type": "string", "description": "`full_time`, `part_time`, `contract` or `intern`.", "enum": [ "full_time", "part_time", "contract", "intern" ] }, "category": { "type": [ "string", "null" ], "description": "The category id." }, "categoryName": { "type": [ "string", "null" ], "description": "The category's name." }, "salaryMin": { "type": [ "number", "null" ], "description": "The lower end of the pay range, or `null`." }, "salaryMax": { "type": [ "number", "null" ], "description": "The upper end of the pay range, or `null`." }, "salaryType": { "type": "string", "description": "What the salary figures are per: `hour`, `week`, `month` or `year`.", "enum": [ "hour", "week", "month", "year" ] }, "requirements": { "type": "string", "description": "What the applicant needs. Empty string if none." }, "shiftTiming": { "type": "string", "description": "The working hours or shifts. Empty string if none." }, "benefits": { "type": "string", "description": "Benefits offered. Empty string if none." }, "applicationDeadline": { "type": [ "string", "null" ], "format": "date-time", "description": "The last moment applicants can be added, or `null`." }, "status": { "type": "string", "description": "`open`: accepting applicants. `closed`: not accepting applicants. `filled`: closed because someone was hired.", "enum": [ "open", "filled", "closed" ] }, "critical": { "type": "boolean", "description": "Whether the job is marked as a priority." }, "screeningQuestionnaireIds": { "type": "array", "description": "The screening questionnaires attached to the job. When present, the interview asks their questions.", "items": { "type": "string" } }, "externalId": { "type": [ "string", "null" ], "description": "Your own id for this job, if you gave one." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the job was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the job was last changed." } }, "required": [ "id", "object", "title", "description", "department", "location", "employmentType", "category", "categoryName", "salaryMin", "salaryMax", "salaryType", "requirements", "shiftTiming", "benefits", "applicationDeadline", "status", "critical", "screeningQuestionnaireIds", "externalId", "createdAt", "updatedAt" ] }, "ExperienceEntry": { "type": "object", "description": "One position from the resume.", "properties": { "company": { "type": "string", "description": "The employer." }, "title": { "type": "string", "description": "The job title held." }, "startDate": { "type": "string", "description": "When it started, as written in the resume (for example `2019-03`)." }, "endDate": { "type": "string", "description": "When it ended, or empty if current." }, "description": { "type": "string", "description": "What they did there." } } }, "EducationEntry": { "type": "object", "description": "One education entry from the resume.", "properties": { "institution": { "type": "string", "description": "The school or college." }, "degree": { "type": "string", "description": "The degree or certificate." }, "field": { "type": "string", "description": "The field of study." }, "startDate": { "type": "string", "description": "When it started, as written in the resume." }, "endDate": { "type": "string", "description": "When it ended, as written in the resume." } } }, "ApplicantResume": { "type": "object", "description": "The applicant's resume and its processing state.", "properties": { "status": { "type": "string", "description": "`none`: no resume uploaded. `pending`: uploaded and being processed. `parsed`: processed; the profile is filled in. `failed`: could not be read (see `error`).", "enum": [ "none", "pending", "parsed", "failed" ] }, "fileName": { "type": [ "string", "null" ], "description": "The uploaded file's name." }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the resume was uploaded." }, "error": { "type": [ "string", "null" ], "description": "Why processing failed, when `status` is `failed`." } }, "required": [ "status", "fileName", "uploadedAt", "error" ] }, "ApplicantMatch": { "type": "object", "description": "Pre-interview match: how well the resume fits the job. Produced after the resume is processed.", "properties": { "status": { "type": "string", "description": "`none`: not scored (no resume or job). `pending`: being scored. `scored`: `score` is available. `failed`: scoring failed.", "enum": [ "none", "pending", "scored", "failed" ] }, "score": { "type": [ "number", "null" ], "description": "How well the resume fits the job, 0-100, or `null` until scored." }, "reasoning": { "type": [ "string", "null" ], "description": "One sentence explaining the score." }, "strengths": { "type": "array", "description": "What in the resume supports the score.", "items": { "type": "string" } }, "gaps": { "type": "array", "description": "What the job needs that the resume does not show.", "items": { "type": "string" } } }, "required": [ "status", "score", "reasoning", "strengths", "gaps" ] }, "ApplicantProfile": { "type": "object", "description": "What was read from the resume. Empty until `resume.status` is `parsed`. Included when retrieving one applicant, not in lists.", "properties": { "skills": { "type": "array", "description": "Skills found in the resume.", "items": { "type": "string" } }, "certifications": { "type": "array", "description": "Certifications found in the resume.", "items": { "type": "string" } }, "experience": { "type": "array", "description": "Positions found in the resume.", "items": { "$ref": "#/components/schemas/ExperienceEntry" } }, "education": { "type": "array", "description": "Education found in the resume.", "items": { "$ref": "#/components/schemas/EducationEntry" } } }, "required": [ "skills", "certifications", "experience", "education" ] }, "ApplicantCoverLetter": { "type": "object", "description": "Whether the applicant has a cover letter. The text itself is returned by `GET /v1/applicants/{id}`.", "properties": { "present": { "type": "boolean", "description": "Whether the applicant has a cover letter." }, "source": { "type": [ "string", "null" ], "description": "`file` (uploaded in the app) or `pasted` (text, e.g. sent through the API).", "enum": [ "file", "pasted", null ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was added or last edited." } }, "required": [ "present", "source", "updatedAt" ] }, "Applicant": { "type": "object", "description": "A person who applied for a job.", "properties": { "id": { "type": "string", "description": "The applicant's id (`cand_…`)." }, "object": { "type": "string", "description": "Always `applicant`.", "enum": [ "applicant" ] }, "name": { "type": "string", "description": "The applicant's name." }, "email": { "type": "string", "description": "Email address. Empty string if none." }, "phone": { "type": "string", "description": "Phone number. Empty string if none." }, "jobId": { "type": [ "string", "null" ], "description": "The job they applied for." }, "status": { "type": "string", "description": "Where the applicant is in your pipeline: `new`, `contacted`, `interview_ready` (an interview was scheduled or a scheduling link sent), `interviewed` (an interview took place), `hired`, `rejected`. Cenivoz moves an applicant forward automatically when an interview is scheduled and when it ends, but never backwards and never over `hired` / `rejected`.", "enum": [ "new", "contacted", "interview_ready", "interviewed", "hired", "rejected" ] }, "location": { "type": "string", "description": "Where the applicant lives. Empty string if unknown." }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile link. Empty string if none." }, "portfolioUrl": { "type": "string", "description": "Portfolio or website link. Empty string if none." }, "expectedSalary": { "type": "string", "description": "What they are asking for. Empty string if unknown." }, "noticePeriod": { "type": "string", "description": "How soon they could start. Empty string if unknown." }, "source": { "type": "string", "description": "Where the applicant came from." }, "tags": { "type": "array", "description": "Free labels.", "items": { "type": "string" } }, "resume": { "$ref": "#/components/schemas/ApplicantResume", "description": "The resume and how far its processing has got." }, "match": { "$ref": "#/components/schemas/ApplicantMatch", "description": "The pre-interview match: how well the resume fits the job." }, "coverLetter": { "$ref": "#/components/schemas/ApplicantCoverLetter", "description": "Whether there is a cover letter." }, "welcomeEmail": { "type": "string", "description": "The welcome email with a booking link: `none` (not requested), `pending` (waiting for the resume to be processed), `sending`, `sent` or `skipped` (it could not be sent, e.g. no email address).", "enum": [ "none", "pending", "sending", "sent", "skipped" ] }, "profile": { "$ref": "#/components/schemas/ApplicantProfile", "description": "What was read from the resume. Only when retrieving one applicant (and in applicant events)." }, "coverLetterText": { "type": [ "string", "null" ], "description": "The cover letter text the interviewer reads, or `null`. Only when retrieving one applicant." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the applicant was archived, or `null` if active." }, "externalId": { "type": [ "string", "null" ], "description": "Your own id for this applicant, if you gave one." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the applicant was added." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the applicant was last changed (including automatic changes such as the resume being processed)." } }, "required": [ "id", "object", "name", "status", "resume", "match", "coverLetter", "welcomeEmail", "createdAt", "updatedAt" ] }, "ResumeStatus": { "type": "object", "description": "How far the applicant's resume has got.", "properties": { "applicantId": { "type": "string", "description": "The applicant." }, "status": { "type": "string", "description": "`none`, `pending`, `parsed` or `failed`. See the applicant's `resume.status`.", "enum": [ "none", "pending", "parsed", "failed" ] }, "fileName": { "type": [ "string", "null" ], "description": "The uploaded file's name." }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the resume was uploaded." }, "error": { "type": [ "string", "null" ], "description": "Why processing failed, when `status` is `failed`." }, "matchStatus": { "type": "string", "description": "State of the resume-versus-job scoring that follows processing: `none`, `pending`, `scored` or `failed`.", "enum": [ "none", "pending", "scored", "failed" ] } }, "required": [ "applicantId", "status", "fileName", "uploadedAt", "error", "matchStatus" ] }, "Interview": { "type": "object", "description": "An interview.", "properties": { "id": { "type": "string", "description": "The interview's id (`sess_…`). It is also the code in `interviewUrl`." }, "object": { "type": "string", "description": "Always `interview`.", "enum": [ "interview" ] }, "applicantId": { "type": "string", "description": "The applicant being interviewed." }, "jobId": { "type": [ "string", "null" ], "description": "The job the applicant applied for." }, "medium": { "type": "string", "description": "`web` or `phone`.", "enum": [ "web", "phone" ] }, "status": { "type": "string", "description": "`awaiting_booking`: a scheduling link was sent and the applicant has not picked a time. `scheduled`: waiting to happen. `in_progress`: happening now. `completed`: ran to the end. `left_early`: the applicant ended it early or the connection dropped. `missed`: the time passed and the applicant never joined. `cancelled`: cancelled, or replaced by a newer interview for the same applicant. `error`: could not take place (for example a phone call that was not answered).", "enum": [ "awaiting_booking", "scheduled", "in_progress", "completed", "left_early", "missed", "cancelled", "error" ] }, "language": { "type": "string", "description": "The interview language code." }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it is scheduled for. `null` for a web link that works right away, or while awaiting booking." }, "timezone": { "type": "string", "description": "The applicant's time zone if known, otherwise `UTC`." }, "videoRequired": { "type": "boolean", "description": "Whether the applicant's camera was asked for." }, "plannedDurationMinutes": { "type": "integer", "description": "The planned length in minutes." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the applicant joined, or `null` if it has not started." }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended, or `null` if it has not ended." }, "durationSeconds": { "type": [ "integer", "null" ], "description": "How long it lasted, once ended." }, "completionType": { "type": [ "string", "null" ], "description": "How it ended: `completed` (reached the end), `ended_early` (the applicant left) or `disconnected` (the connection dropped and did not return). `null` until it ends.", "enum": [ "completed", "ended_early", "disconnected", null ] }, "scoringStatus": { "type": "string", "description": "The evaluation that follows the interview. `pending`: not ready (or the interview has not ended). `scored`: available from `GET /v1/interviews/{id}/result`. `insufficient_data`: too little was said to evaluate. `failed`: it could not be produced.", "enum": [ "pending", "scored", "insufficient_data", "failed" ] }, "recordingConsent": { "type": [ "object", "null" ], "description": "The applicant's own agreement to being recorded. A `web` interview cannot start without it. `null` while they have not been asked yet, and for a `phone` interview scheduled for them (there is no page to ask on).", "properties": { "givenAt": { "type": "string", "format": "date-time", "description": "When the applicant agreed." }, "scope": { "type": "array", "description": "What they agreed to have recorded: `audio`, or `audio` and `video` (video only exists while their camera was on).", "items": { "type": "string", "description": "`audio` or `video`.", "enum": [ "audio", "video" ] } }, "channel": { "type": "string", "description": "Where they agreed: `interview_page` (the box on the interview page, before starting) or `booking_page` (when booking a phone interview).", "enum": [ "interview_page", "booking_page" ] }, "version": { "type": "string", "description": "Which wording of the consent statement they agreed to (a date)." } } }, "interviewUrl": { "type": [ "string", "null" ], "description": "The link to give the applicant, for a `web` interview that can still be taken. `null` otherwise." }, "externalId": { "type": [ "string", "null" ], "description": "Your own id for this interview, if you gave one." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the interview was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last changed." } }, "required": [ "id", "object", "applicantId", "jobId", "medium", "status", "language", "scheduledAt", "timezone", "videoRequired", "plannedDurationMinutes", "startedAt", "endedAt", "durationSeconds", "completionType", "scoringStatus", "recordingConsent", "interviewUrl", "externalId", "createdAt", "updatedAt" ] }, "ScoreSet": { "type": "object", "description": "The scores, each 0-100.", "properties": { "overall": { "type": "integer", "description": "The overall score, 0-100." }, "communication": { "type": "integer", "description": "How clearly the applicant communicated, 0-100." }, "technical": { "type": "integer", "description": "Technical knowledge for the role, 0-100." }, "problemSolving": { "type": "integer", "description": "How the applicant approached problems, 0-100." }, "confidence": { "type": "integer", "description": "How confident the applicant came across, 0-100." }, "behavior": { "type": "integer", "description": "Professionalism and attitude, 0-100." } }, "required": [ "overall", "communication", "technical", "problemSolving", "confidence", "behavior" ] }, "ScreeningAnswer": { "type": "object", "description": "How one screening question went.", "properties": { "question": { "type": "string", "description": "The screening question that was asked." }, "type": { "type": "string", "description": "`yes_no` (has a required answer) or `open` (free answer).", "enum": [ "open", "yes_no" ] }, "status": { "type": "string", "description": "`pending`, `asked`, `answered` or `skipped`.", "enum": [ "pending", "asked", "answered", "skipped" ] }, "answer": { "type": [ "string", "null" ], "description": "What the applicant answered: `yes` / `no` for a yes/no question, else their answer. `null` if unanswered." }, "expectedAnswer": { "type": [ "string", "null" ], "description": "For `yes_no`: the answer the job needs.", "enum": [ "yes", "no", null ] }, "summary": { "type": [ "string", "null" ], "description": "A short summary of what the applicant said." } }, "required": [ "question", "type", "status", "answer", "expectedAnswer", "summary" ] }, "InterviewResult": { "type": "object", "description": "The outcome of an interview. The same JSON is pushed in the `interview.completed` event.", "properties": { "interviewId": { "type": "string", "description": "The interview." }, "applicantId": { "type": "string", "description": "The applicant." }, "jobId": { "type": [ "string", "null" ], "description": "The job the applicant applied for." }, "status": { "type": "string", "description": "`awaiting_booking`: a scheduling link was sent and the applicant has not picked a time. `scheduled`: waiting to happen. `in_progress`: happening now. `completed`: ran to the end. `left_early`: the applicant ended it early or the connection dropped. `missed`: the time passed and the applicant never joined. `cancelled`: cancelled, or replaced by a newer interview for the same applicant. `error`: could not take place (for example a phone call that was not answered).", "enum": [ "awaiting_booking", "scheduled", "in_progress", "completed", "left_early", "missed", "cancelled", "error" ] }, "completionType": { "type": [ "string", "null" ], "description": "How it ended: `completed`, `ended_early` or `disconnected`. `null` until it ends." }, "scoringStatus": { "type": "string", "description": "`pending`: the evaluation is not ready yet (poll again, or wait for `interview.completed`). `scored`: `scores` and the feedback below are filled in. `insufficient_data`: too little was said to evaluate, so there are no scores. `failed`: the evaluation could not be produced.", "enum": [ "pending", "scored", "insufficient_data", "failed" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the applicant joined." }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended." }, "durationSeconds": { "type": [ "integer", "null" ], "description": "How long it lasted." }, "scores": { "anyOf": [ { "$ref": "#/components/schemas/ScoreSet" }, { "type": "null" } ], "description": "The scores, each 0-100, or `null` unless `scoringStatus` is `scored`." }, "recommendation": { "type": [ "string", "null" ], "description": "The overall recommendation: `Strong Hire`, `Hire`, `Borderline` or `No Hire`. `null` unless `scoringStatus` is `scored`.", "enum": [ "Strong Hire", "Hire", "Borderline", "No Hire", null ] }, "summary": { "type": [ "string", "null" ], "description": "A paragraph summarising the interview." }, "strengths": { "type": "array", "description": "What the applicant did well.", "items": { "type": "string" } }, "weaknesses": { "type": "array", "description": "Where the applicant was weaker.", "items": { "type": "string" } }, "missingSkills": { "type": "array", "description": "Skills the job needs that the applicant did not demonstrate.", "items": { "type": "string" } }, "recommendedTraining": { "type": "array", "description": "Training that would help.", "items": { "type": "string" } }, "screening": { "type": "array", "description": "How each screening question went. Empty if the job has no screening questions.", "items": { "$ref": "#/components/schemas/ScreeningAnswer" } }, "externalId": { "type": [ "string", "null" ], "description": "Your own id for this interview, if you gave one." } }, "required": [ "interviewId", "applicantId", "jobId", "status", "completionType", "scoringStatus", "startedAt", "endedAt", "durationSeconds", "scores", "recommendation", "summary", "strengths", "weaknesses", "missingSkills", "recommendedTraining", "screening", "externalId" ] }, "TranscriptEntry": { "type": "object", "description": "One turn of the conversation.", "properties": { "speaker": { "type": "string", "description": "Who spoke: `interviewer` or `applicant`.", "enum": [ "interviewer", "applicant" ] }, "message": { "type": "string", "description": "What was said." }, "elapsedMs": { "type": "integer", "description": "Milliseconds from the start of the interview." }, "timestamp": { "type": "string", "format": "date-time", "description": "When it was said." } }, "required": [ "speaker", "message", "elapsedMs", "timestamp" ] }, "Transcript": { "type": "object", "description": "What was said in an interview.", "properties": { "interviewId": { "type": "string", "description": "The interview." }, "entries": { "type": "array", "description": "The conversation, in order.", "items": { "$ref": "#/components/schemas/TranscriptEntry" } } }, "required": [ "interviewId", "entries" ] }, "Recording": { "type": "object", "description": "Temporary links to the interview recording.", "properties": { "interviewId": { "type": "string", "description": "The interview." }, "audioUrl": { "type": [ "string", "null" ], "description": "A link to the recording (WAV, supports HTTP range requests), or `null` if there is none. It works without authentication until `expiresAt`: do not share it." }, "videoUrls": { "type": "array", "description": "Links to the applicant's camera recordings (WebM), if video was recorded. Same expiry.", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the links stop working (one hour). Ask again for fresh ones." } }, "required": [ "interviewId", "audioUrl", "videoUrls", "expiresAt" ] }, "StatsPeriod": { "type": "object", "description": "The period the figures cover.", "properties": { "from": { "type": "string", "format": "date-time", "description": "The start of the period (inclusive)." }, "to": { "type": "string", "format": "date-time", "description": "The end of the period (exclusive)." }, "jobId": { "type": [ "string", "null" ], "description": "The job the figures are limited to, or `null` for all jobs." } }, "required": [ "from", "to" ] }, "StatsConducted": { "type": "object", "description": "Interviews that took place.", "properties": { "started": { "type": "integer", "description": "Interviews that began in the period." }, "completed": { "type": "integer", "description": "Of those, how many ran to the end (`completionType` `completed`)." }, "leftEarly": { "type": "integer", "description": "Of those, how many ended early or disconnected." }, "inProgress": { "type": "integer", "description": "Of those, how many are happening right now." }, "averageScore": { "type": [ "number", "null" ], "description": "The average overall score of those that were scored, to one decimal, or `null` if none were." }, "averageDurationSeconds": { "type": [ "number", "null" ], "description": "The average length of those that ended, in seconds, or `null` if none ended." } }, "required": [ "started", "completed", "leftEarly", "inProgress", "averageScore", "averageDurationSeconds" ] }, "StatsOverview": { "type": "object", "description": "How many applicants applied and how many interviews were conducted.", "properties": { "period": { "$ref": "#/components/schemas/StatsPeriod", "description": "The period the figures cover." }, "applicants": { "type": "object", "description": "Applicants.", "properties": { "applied": { "type": "integer", "description": "Applicants added in the period." }, "byStatus": { "type": "object", "description": "Those applicants counted by their pipeline status now: `{ \"new\": 4, \"hired\": 1 }`. Statuses with none are omitted.", "additionalProperties": { "type": "integer" } }, "archived": { "type": "integer", "description": "Of those, how many are archived now." } }, "required": [ "applied", "byStatus", "archived" ] }, "interviews": { "type": "object", "description": "Interviews.", "properties": { "scheduled": { "type": "integer", "description": "Interviews created in the period, not counting cancelled ones." }, "cancelled": { "type": "integer", "description": "Interviews created in the period that were cancelled or replaced." }, "conducted": { "$ref": "#/components/schemas/StatsConducted" } }, "required": [ "scheduled", "cancelled", "conducted" ] } }, "required": [ "period", "applicants", "interviews" ] }, "StatsJobRow": { "type": "object", "description": "Figures for one job.", "properties": { "jobId": { "type": "string", "description": "The job these figures are for." }, "title": { "type": [ "string", "null" ], "description": "The job title." }, "status": { "type": [ "string", "null" ], "description": "The job's status now." }, "applicants": { "type": "integer", "description": "Applicants added in the period." }, "interviewsStarted": { "type": "integer", "description": "Interviews that began in the period." }, "interviewsCompleted": { "type": "integer", "description": "Of those, how many ran to the end." }, "averageScore": { "type": [ "number", "null" ], "description": "The average overall score of those scored, or `null`." } }, "required": [ "jobId", "title", "status", "applicants", "interviewsStarted", "interviewsCompleted", "averageScore" ] }, "StatsJobs": { "type": "object", "description": "Figures per job.", "properties": { "period": { "$ref": "#/components/schemas/StatsPeriod", "description": "The period the figures cover." }, "data": { "type": "array", "description": "One row per job with activity in the period, plus every open job. Sorted by applicants, most first.", "items": { "$ref": "#/components/schemas/StatsJobRow" } } }, "required": [ "period", "data" ] }, "Event": { "type": "object", "description": "Something that happened. Webhooks POST exactly this JSON.", "properties": { "id": { "type": "string", "description": "The event's id (`evt_…`). Unique and stable: the same event keeps its id on every retry and redelivery. De-duplicate on it." }, "object": { "type": "string", "description": "Always `event`.", "enum": [ "event" ] }, "type": { "type": "string", "description": "What happened. See the event reference.", "enum": [ "job.created", "job.updated", "applicant.created", "applicant.updated", "applicant.status_changed", "applicant.resume_parsed", "applicant.resume_failed", "interview.invited", "interview.scheduled", "interview.started", "interview.completed", "interview.missed", "interview.cancelled", "interview.failed", "webhook.test" ] }, "apiVersion": { "type": "string", "description": "The API version the payload follows." }, "environment": { "type": "string", "description": "`sandbox` or `production`.", "enum": [ "sandbox", "production" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the change happened (not when it was sent)." }, "data": { "type": "object", "description": "The event's content: the record as the REST API returns it (see each event type)." } }, "required": [ "id", "object", "type", "apiVersion", "environment", "createdAt", "data" ] }, "WebhookEndpoint": { "type": "object", "description": "A URL that receives your events (set up on the Cenivoz Developers page).", "properties": { "id": { "type": "string", "description": "The endpoint's id (`whe_…`)." }, "object": { "type": "string", "description": "Always `webhook_endpoint`.", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string", "description": "Where events are sent." }, "description": { "type": "string", "description": "Your note about it. Empty string if none." }, "events": { "type": "array", "description": "The event types it receives. Empty means every type.", "items": { "type": "string" } }, "status": { "type": "string", "description": "`active` or `disabled` (by you, or automatically after many failures in a row).", "enum": [ "active", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ], "description": "Why it is disabled, when it is." }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was added." } }, "required": [ "id", "object", "url", "description", "events", "status", "disabledReason", "createdAt" ] }, "WebhookDelivery": { "type": "object", "description": "One event on its way to one endpoint.", "properties": { "id": { "type": "string", "description": "The delivery's id (`whd_…`)." }, "object": { "type": "string", "description": "Always `webhook_delivery`.", "enum": [ "webhook_delivery" ] }, "eventId": { "type": "string", "description": "The event being delivered (`evt_…`)." }, "endpointId": { "type": "string", "description": "The endpoint it was sent to." }, "type": { "type": "string", "description": "The event type, e.g. `interview.completed`." }, "kind": { "type": "string", "description": "`event`: a normal delivery. `redelivery`: sent again on request. `test`: a test event.", "enum": [ "event", "test", "redelivery" ] }, "status": { "type": "string", "description": "`pending`: waiting to be sent or retried. `sending`: in flight. `succeeded`: your server answered 2xx. `failed`: a test event that was not accepted. `dead`: gave up after all attempts (it can still be redelivered).", "enum": [ "pending", "sending", "succeeded", "failed", "dead" ] }, "attemptCount": { "type": "integer", "description": "How many times it was tried." }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt is due, while `pending`." }, "lastStatusCode": { "type": [ "integer", "null" ], "description": "The HTTP status your server answered on the last attempt, if it answered." }, "lastError": { "type": [ "string", "null" ], "description": "Why the last attempt failed, if it did." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the delivery was queued." } }, "required": [ "id", "object", "eventId", "endpointId", "type", "kind", "status", "attemptCount", "nextAttemptAt", "lastStatusCode", "lastError", "createdAt" ] }, "SimulationResult": { "type": "object", "description": "The interview after the simulation. The matching events are sent to your webhooks as usual.", "properties": { "simulated": { "type": "boolean", "description": "Always `true`." }, "interview": { "$ref": "#/components/schemas/Interview", "description": "The interview as it is now." } }, "required": [ "simulated", "interview" ] }, "SandboxReset": { "type": "object", "description": "The result of resetting the sandbox.", "properties": { "reset": { "type": "boolean", "description": "Always `true`." }, "deleted": { "type": "object", "description": "How many of each were deleted.", "properties": { "jobs": { "type": "integer", "description": "Jobs deleted." }, "applicants": { "type": "integer", "description": "Applicants deleted." }, "interviews": { "type": "integer", "description": "Interviews deleted." }, "events": { "type": "integer", "description": "Events and their webhook deliveries deleted." } }, "required": [ "jobs", "applicants", "interviews", "events" ] } }, "required": [ "reset", "deleted" ] }, "TestEventResult": { "type": "object", "description": "Test events on their way.", "properties": { "queued": { "type": "integer", "description": "How many test deliveries were queued (one per active endpoint, or the one asked for)." }, "deliveries": { "type": "array", "description": "The queued deliveries. Follow them with `GET /v1/webhook-deliveries`.", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "queued", "deliveries" ] }, "CategoryList": { "type": "object", "description": "A page of job categories.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Category" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "QuestionnaireList": { "type": "object", "description": "A page of screening questionnaires.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Questionnaire" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "JobList": { "type": "object", "description": "A page of jobs, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Job" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "ApplicantList": { "type": "object", "description": "A page of applicants, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Applicant" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "InterviewList": { "type": "object", "description": "A page of interviews, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Interview" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "EventList": { "type": "object", "description": "A page of events, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/Event" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "WebhookEndpointList": { "type": "object", "description": "Your webhook endpoints in this environment.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] }, "WebhookDeliveryList": { "type": "object", "description": "A page of webhook deliveries, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`.", "enum": [ "list" ] }, "data": { "type": "array", "description": "The page of results.", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "hasMore": { "type": "boolean", "description": "`true` when another page follows." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `?cursor=` to get the next page. `null` on the last page." } }, "required": [ "object", "data", "hasMore", "nextCursor" ] } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Client credentials: enter your client ID and secret and the token is fetched for you.", "flows": { "clientCredentials": { "tokenUrl": "https://connect-sandbox.cenivoz.com/oauth/token", "scopes": { "jobs:read": "List and view jobs, job categories, screening questionnaires and interview languages", "jobs:write": "Create and update jobs, open and close them", "applicants:read": "List and view applicants and their resume status", "applicants:write": "Create, update, archive and restore applicants; upload resumes and cover letters", "interviews:read": "List interviews; read their status, results, transcripts and recordings", "interviews:write": "Schedule, reschedule and cancel interviews; send scheduling links", "stats:read": "Read applicant and interview statistics", "events:read": "List the events that happened (the same events webhooks push)", "webhooks:read": "Read the webhook delivery history", "webhooks:write": "Redeliver webhook events and send test events" } } } }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Or paste an access token you already have." } } }, "x-error-catalog": [ { "status": 400, "code": "invalid_json", "title": "The body is not valid JSON", "retry": "never" }, { "status": 400, "code": "invalid_request", "title": "The request is malformed", "retry": "never" }, { "status": 400, "code": "phone_unavailable", "title": "Phone interviews are not available", "retry": "later" }, { "status": 401, "code": "unauthorized", "title": "Missing, invalid, expired or revoked access token", "retry": "fix" }, { "status": 403, "code": "access_disabled", "title": "API access is switched off for this environment", "retry": "fix" }, { "status": 403, "code": "company_suspended", "title": "The company account is suspended", "retry": "fix" }, { "status": 403, "code": "forbidden", "title": "Not allowed with this credential", "retry": "never" }, { "status": 403, "code": "insufficient_scope", "title": "The credential lacks a required scope", "retry": "fix" }, { "status": 403, "code": "wrong_environment", "title": "Token sent to the other environment", "retry": "never" }, { "status": 404, "code": "not_found", "title": "No such record (or endpoint)", "retry": "never" }, { "status": 409, "code": "applicant_archived", "title": "The applicant is archived", "retry": "fix" }, { "status": 409, "code": "conflict", "title": "A concurrent change collided", "retry": "later" }, { "status": 409, "code": "duplicate_external_id", "title": "You already used this externalId", "retry": "never" }, { "status": 409, "code": "email_required", "title": "The applicant has no email address", "retry": "fix" }, { "status": 409, "code": "endpoint_disabled", "title": "The webhook endpoint is switched off", "retry": "fix" }, { "status": 409, "code": "invalid_state", "title": "Not possible in the record's current state", "retry": "never" }, { "status": 409, "code": "no_endpoint", "title": "No webhook endpoint", "retry": "fix" }, { "status": 409, "code": "phone_required", "title": "The applicant has no phone number", "retry": "fix" }, { "status": 409, "code": "request_in_progress", "title": "The same Idempotency-Key is still being processed", "retry": "later" }, { "status": 409, "code": "resume_required", "title": "The applicant has no processed resume", "retry": "fix" }, { "status": 409, "code": "slot_taken", "title": "Another interview occupies that time", "retry": "fix" }, { "status": 413, "code": "payload_too_large", "title": "The request is too large", "retry": "never" }, { "status": 415, "code": "unsupported_media_type", "title": "Unsupported content type or file", "retry": "never" }, { "status": 422, "code": "idempotency_conflict", "title": "The Idempotency-Key was used for a different request", "retry": "never" }, { "status": 422, "code": "validation_failed", "title": "A field is missing or invalid", "retry": "never" }, { "status": 429, "code": "rate_limited", "title": "Too many requests", "retry": "later" }, { "status": 500, "code": "internal_error", "title": "Something went wrong on our side", "retry": "later" }, { "status": 503, "code": "queue_unavailable", "title": "A dependency is briefly unavailable", "retry": "later" } ] }