{"openapi":"3.1.0","info":{"title":"CarvOS","summary":"Universal platform API for ATS integrations with AI-powered candidate analysis.","description":"\nCarvOS provides a standardized API for Applicant Tracking Systems (ATS) to integrate\nAI-powered recruitment capabilities.\n\n## Authentication\n\nAll endpoints require an `X-API-Key` header. Entity operations additionally require\n`X-ATS-Client-ID` (maps to workspace) and `X-ATS-User-ID` (maps to member).\n\n## Data Ingestion\n\nTwo equivalent methods — both return `202 Accepted` and process asynchronously:\n\n| Method | Auth | Endpoint |\n|--------|------|----------|\n| **REST API** | `X-API-Key` + context headers | `POST /v1/{entity}` |\n| **Incoming Webhooks** | HMAC-SHA256 signature | `POST /v1/webhooks/{ats_id}` |\n\n## Outgoing Webhooks\n\nCarvOS sends results to your configured endpoint via HMAC-signed webhooks.\nSignature format: `X-Webhook-Signature: t={timestamp},v1={hmac_sha256}`.\nSigned payload: `{timestamp}.{request_body}` (timestamp bytes + dot + raw body bytes).\n\n## Webhook Signature Verification\n\n```python\nimport hmac, hashlib\nsigned_payload = f\"{timestamp}.\".encode() + body\nexpected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()\nassert hmac.compare_digest(expected, provided_signature)\n```\n\nSignatures older than 5 minutes are rejected. Delivery timeout is 5 seconds.\n\nSee [/docs](/docs/) for integration guides and flow documentation.\n","contact":{"name":"Carv Engineering","email":"engineering@carv.com"},"license":{"name":"Proprietary"},"version":"0.1.0"},"servers":[{"url":"https://carvos.carv.com"}],"paths":{"/healthcheck":{"get":{"summary":"Healthcheck","description":"Health check endpoint to verify the service is running.","operationId":"healthcheck_healthcheck_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Healthcheck Healthcheck Get"}}}}}}},"/v1/workspaces":{"post":{"tags":["Workspaces"],"summary":"Create workspace","description":"Submit a new workspace for processing. Requires X-ATS-Client-ID header.","operationId":"create_workspace_v1_workspaces_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceCreateInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"422":{"description":"X-ATS-User-ID header is required for workspace creation"}}}},"/v1/workspaces/{client_id}":{"patch":{"tags":["Workspaces"],"summary":"Update workspace","description":"Submit workspace updates for processing.","operationId":"update_workspace_v1_workspaces__client_id__patch","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","title":"Client Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUpdateInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Workspace not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Workspaces"],"summary":"Delete workspace","description":"Submit workspace deletion request for processing.","operationId":"delete_workspace_v1_workspaces__client_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","title":"Client Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Workspace not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/workspaces/{client_id}/members":{"post":{"tags":["Workspaces","Workspaces"],"summary":"Create member","description":"Submit a new member for processing.","operationId":"create_member_v1_workspaces__client_id__members_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","description":"Client ID (workspace)","title":"Client Id"},"description":"Client ID (workspace)"},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberCreateInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"400":{"description":"X-ATS-User-ID header is required for member creation"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/workspaces/{client_id}/members/{user_id}":{"delete":{"tags":["Workspaces","Workspaces"],"summary":"Delete member","description":"Submit member deletion request for processing.","operationId":"delete_member_v1_workspaces__client_id__members__user_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","description":"Client ID (workspace)","title":"Client Id"},"description":"Client ID (workspace)"},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"User ID (member)","title":"User Id"},"description":"User ID (member)"},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Member not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/applications":{"post":{"tags":["Applications"],"summary":"Create application","description":"Submit an application for AI-powered analysis.\n\nThe application references candidate and vacancy by their IDs.\nThe application is queued for asynchronous processing. Poll the returned\nresource URL or listen for webhook events to track analysis progress.","operationId":"create_application_v1_applications_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationInput"}}}},"responses":{"202":{"description":"Accepted confirmation with resource URL for status polling","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/applications/{application_id}":{"patch":{"tags":["Applications"],"summary":"Update application","description":"Submit application updates for processing.","operationId":"update_application_v1_applications__application_id__patch","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","title":"Application Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialPartialApplicationInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Application not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Applications"],"summary":"Delete application","description":"Submit application deletion request for processing.","operationId":"delete_application_v1_applications__application_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","title":"Application Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Application not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/candidates":{"post":{"tags":["Candidates"],"summary":"Create candidate","description":"Submit a new candidate profile for processing.","operationId":"create_candidate_v1_candidates_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/candidates/{candidate_id}":{"patch":{"tags":["Candidates"],"summary":"Update candidate","description":"Submit candidate profile updates for processing.","operationId":"update_candidate_v1_candidates__candidate_id__patch","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","title":"Candidate Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialPartialCandidateInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Candidate not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Candidates"],"summary":"Delete candidate","description":"Submit candidate deletion request for processing.","operationId":"delete_candidate_v1_candidates__candidate_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","title":"Candidate Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Candidate not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vacancies":{"post":{"tags":["Vacancies"],"summary":"Create vacancy","description":"Submit a new vacancy requisition for processing.","operationId":"create_vacancy_v1_vacancies_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VacancyInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vacancies/{vacancy_id}":{"patch":{"tags":["Vacancies"],"summary":"Update vacancy","description":"Submit vacancy requisition updates for processing.","operationId":"update_vacancy_v1_vacancies__vacancy_id__patch","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"vacancy_id","in":"path","required":true,"schema":{"type":"string","title":"Vacancy Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialPartialVacancyInput"}}}},"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Vacancy not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Vacancies"],"summary":"Delete vacancy","description":"Submit vacancy deletion request for processing.","operationId":"delete_vacancy_v1_vacancies__vacancy_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"vacancy_id","in":"path","required":true,"schema":{"type":"string","title":"Vacancy Id"}},{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"202":{"description":"Accepted confirmation with reference ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"404":{"description":"Vacancy not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/meetings/calendars/connect":{"post":{"tags":["Meetings"],"summary":"Generate calendar connection URL","description":"Generate an OAuth URL for connecting a member's calendar.\n\nThe ATS should redirect their user to the returned `oauth_url`. After the user\ncompletes the OAuth flow, they will be redirected to the provided `return_url`\nwith query parameters indicating success or failure.\n\n**Supported providers:**\n- Google Calendar\n- Microsoft Outlook\n\n**After OAuth redirect:**\n- Success: `{return_url}?status=success`\n- Error: `{return_url}?status=error&error={message}`\n\n**Note:** If the member already has a calendar connected, this endpoint will\nreturn an error. Use the disconnect endpoint first, then connect the new calendar.","operationId":"connect_calendar_v1_meetings_calendars_connect_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarConnectRequest"}}}},"responses":{"200":{"description":"OAuth URL for calendar connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarConnectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/meetings/calendars":{"delete":{"tags":["Meetings"],"summary":"Disconnect calendar","description":"Disconnect a member's calendar integration.\n\nThis removes the calendar integration and stops automatic meeting recording\nfor this member. The member can reconnect their calendar at any time.","operationId":"disconnect_calendar_v1_meetings_calendars_delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"responses":{"204":{"description":"Calendar disconnected successfully"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/meetings/calendars/settings":{"put":{"tags":["Meetings"],"summary":"Update recording settings","description":"Update the recording settings for a member's calendar integration.\n\n**Available settings:**\n- `record_all_meetings` - Record all meetings automatically\n- `record_internal_only` - Record only internal meetings (within organization)\n- `record_external_only` - Record only external meetings (with outside participants)\n- `record_host_only` - Record only meetings where the member is the host\n- `record_none` - Don't record any meetings automatically","operationId":"update_calendar_settings_v1_meetings_calendars_settings_put","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarSettingsUpdateRequest"}}}},"responses":{"204":{"description":"Settings updated successfully"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/uploads":{"post":{"tags":["Uploads"],"summary":"Upload a file","description":"Upload a binary file to receive a reference ID that can be used in subsequent API calls.\n\n**Supported file types:**\n- Documents: PDF, DOC, DOCX\n\n**Size limit:** 50MB per file\n\nThe returned `carv_file_id` should be included in webhook payloads or other API requests\nthat reference uploaded files (e.g., resumes, meeting recordings).","operationId":"upload_file_v1_uploads_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_file_v1_uploads_post"}}}},"responses":{"201":{"description":"File upload confirmation with reference ID and metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}},"401":{"description":"Missing or invalid API key"},"422":{"description":"Invalid file extension or file exceeds size limit"}}}},"/v1/embeds/candidate-url":{"post":{"tags":["Embeds"],"summary":"Generate embeddable candidate URL","description":"Generate a URL with a Firebase custom token for embedding a candidate profile in an iframe. The token is valid for 1 hour (Firebase SDK constraint, not configurable). The ``expires_in`` field in the response indicates validity.","operationId":"generate_candidate_embed_url_v1_embeds_candidate_url_post","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-ATS-Client-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-Client-Id"}},{"name":"X-ATS-User-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ats-User-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedUrlRequest"}}}},"responses":{"200":{"description":"Embeddable URL with Firebase custom token (1h validity)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedUrlResponse"}}}},"404":{"description":"User mapping not found for ATS user"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{ats_id}":{"post":{"tags":["Incoming Webhooks"],"summary":"Handle webhook events","description":"Per-ATS webhook endpoint. Uses discriminated union on 'event' field for routing.","operationId":"handle_webhook","parameters":[{"name":"ats_id","in":"path","required":true,"schema":{"type":"string","title":"Ats Id"}},{"name":"X-Webhook-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Webhook-Signature"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WorkspaceCreatedPayload"},{"$ref":"#/components/schemas/WorkspaceUpdatedPayload"},{"$ref":"#/components/schemas/WorkspaceDeletedPayload"},{"$ref":"#/components/schemas/MemberCreatedPayload"},{"$ref":"#/components/schemas/MemberDeletedPayload"},{"$ref":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationCreatedPayload"},{"$ref":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationUpdatedPayload"},{"$ref":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationDeletedPayload"},{"$ref":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateCreatedPayload"},{"$ref":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateUpdatedPayload"},{"$ref":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateDeletedPayload"},{"$ref":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyCreatedPayload"},{"$ref":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyUpdatedPayload"},{"$ref":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyDeletedPayload"}],"discriminator":{"propertyName":"event","mapping":{"workspace.created":"#/components/schemas/WorkspaceCreatedPayload","workspace.updated":"#/components/schemas/WorkspaceUpdatedPayload","workspace.deleted":"#/components/schemas/WorkspaceDeletedPayload","member.created":"#/components/schemas/MemberCreatedPayload","member.deleted":"#/components/schemas/MemberDeletedPayload","application.created":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationCreatedPayload","application.updated":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationUpdatedPayload","application.deleted":"#/components/schemas/carvos__domains__applications__incoming_webhooks__models__ApplicationDeletedPayload","candidate.created":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateCreatedPayload","candidate.updated":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateUpdatedPayload","candidate.deleted":"#/components/schemas/carvos__domains__candidates__incoming_webhooks__models__CandidateDeletedPayload","vacancy.created":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyCreatedPayload","vacancy.updated":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyUpdatedPayload","vacancy.deleted":"#/components/schemas/carvos__domains__vacancies__incoming_webhooks__models__VacancyDeletedPayload"}},"title":"Payload"}}}},"responses":{"202":{"description":"Confirmation that the event was accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"webhooks":{"workspace.member_added":{"post":{"summary":"Workspace Member Added","description":"Sent when a new member is added to a workspace. Contains the ATS user identifier.","operationId":"workspace_member_addedworkspace_member_added_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMemberAddedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"workspace.provisioned":{"post":{"summary":"Workspace Provisioned","description":"Sent when a workspace is fully provisioned and ready for use. Contains the workspace name and admin user identifier.","operationId":"workspace_provisionedworkspace_provisioned_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceProvisionedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"application.deleted":{"post":{"summary":"Application Deleted","description":"Sent when an application is deleted. Contains only the application identifier.","operationId":"application_deletedapplication_deleted_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__applications__models__ApplicationDeletedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"application.updated":{"post":{"summary":"Application Updated","description":"Sent when application data is updated. Commonly triggered when AI analysis completes, status changes, or files are attached.","operationId":"application_updatedapplication_updated_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__applications__models__ApplicationUpdatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"application.created":{"post":{"summary":"Application Created","description":"Sent when CarvOS finishes processing a new application. Analysis field may be null if AI processing is still in progress.","operationId":"application_createdapplication_created_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__applications__models__ApplicationCreatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"candidate.deleted":{"post":{"summary":"Candidate Deleted","description":"Sent when a candidate is deleted. Contains only the candidate identifier.","operationId":"candidate_deletedcandidate_deleted_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__candidates__models__CandidateDeletedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"candidate.updated":{"post":{"summary":"Candidate Updated","description":"Sent when candidate data is updated. Contains the updated candidate profile with all current data.","operationId":"candidate_updatedcandidate_updated_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__candidates__models__CandidateUpdatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"candidate.created":{"post":{"summary":"Candidate Created","description":"Sent when CarvOS finishes processing a new candidate. Contains the full normalized candidate profile with all extracted data.","operationId":"candidate_createdcandidate_created_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__candidates__models__CandidateCreatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"vacancy.deleted":{"post":{"summary":"Vacancy Deleted","description":"Sent when a vacancy is deleted. Contains only the vacancy identifier.","operationId":"vacancy_deletedvacancy_deleted_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__vacancies__models__VacancyDeletedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"vacancy.updated":{"post":{"summary":"Vacancy Updated","description":"Sent when vacancy data is updated. Contains the updated vacancy.","operationId":"vacancy_updatedvacancy_updated_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__vacancies__models__VacancyUpdatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"vacancy.created":{"post":{"summary":"Vacancy Created","description":"Sent when CarvOS finishes processing a new vacancy. Contains the full vacancy data with all normalized fields.","operationId":"vacancy_createdvacancy_created_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/carvos__domains__vacancies__models__VacancyCreatedPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"meeting.notes_ready":{"post":{"summary":"Meeting Notes Ready","description":"Sent when AI-generated meeting notes are complete. Contains structured markdown notes with key sections.","operationId":"meeting_notes_readymeeting_notes_ready_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingNotesReadyPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"meeting.summary_ready":{"post":{"summary":"Meeting Summary Ready","description":"Sent when AI-generated summary is complete. Contains a 5-sentence summary in plain text.","operationId":"meeting_summary_readymeeting_summary_ready_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingSummaryReadyPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"meeting.transcript_ready":{"post":{"summary":"Meeting Transcript Ready","description":"Sent when meeting transcript is ready (before AI processing). Contains raw transcript with speaker labels and timestamps.","operationId":"meeting_transcript_readymeeting_transcript_ready_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingTranscriptReadyPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"system.status":{"post":{"summary":"System Status","description":"System status change notification. Sent for maintenance windows or service degradation.","operationId":"system_statussystem_status_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemStatusPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"webhook.test":{"post":{"summary":"Webhook Test","description":"Test webhook for endpoint verification. Sent to verify webhook endpoint configuration.","operationId":"webhook_testwebhook_test_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AcceptedResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Request accepted for processing"},"reference_id":{"type":"string","title":"Reference Id","description":"Server-minted UUID7 correlation identifier for this business flow. Matches `carv.causation.id` in CarvOS logs and traces, the `reference_id` field on outgoing webhook payloads emitted for this flow, and the `X-Carv-Causation-ID` header on outgoing webhook deliveries. Store it alongside your own entity ID to correlate async processing back to this request."}},"type":"object","required":["reference_id"],"title":"AcceptedResponse","description":"Response for async operations that return 202 Accepted."},"Address":{"properties":{"city":{"type":"string","title":"City"},"country":{"type":"string","title":"Country"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"address1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address1"},"address2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address2"},"country_code":{"anyOf":[{"type":"string","pattern":"^\\w{2}$"},{"type":"null"}],"title":"Country Code"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"}},"type":"object","required":["city","country"],"title":"Address","description":"A physical location associated with a vacancy.\n\nInclude the fields your ATS provides. Only `city` and `country` are required."},"AnalysisScore":{"properties":{"value":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Value","description":"Match score from 0 to 100."},"reason":{"type":"string","title":"Reason","description":"Explanation of the score."}},"type":"object","required":["value","reason"],"title":"AnalysisScore","description":"AI match score with supporting rationale."},"Application":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"application_id":{"type":"string","title":"Application Id"},"candidate_id":{"type":"string","title":"Candidate Id"},"vacancy_id":{"type":"string","title":"Vacancy Id"},"analysis":{"anyOf":[{"$ref":"#/components/schemas/ApplicationAnalysis"},{"type":"null"}]}},"type":"object","required":["application_id","candidate_id","vacancy_id"],"title":"Application","description":"Full application for retrieval operations.\n\nUsed for:\n- GET /applications (list)\n- GET /applications/{id} (retrieve)\n- Outgoing webhook payloads\n\nInherits shared fields from ApplicationBase and adds analysis results."},"ApplicationAnalysis":{"properties":{"score":{"anyOf":[{"$ref":"#/components/schemas/AnalysisScore"},{"type":"null"}]}},"type":"object","title":"ApplicationAnalysis","description":"AI analysis results for a candidate-vacancy match."},"ApplicationFiles":{"properties":{"resume":{"anyOf":[{"$ref":"#/components/schemas/FileReference"},{"type":"null"}]},"cover_letter":{"anyOf":[{"$ref":"#/components/schemas/FileReference"},{"type":"null"}]}},"type":"object","title":"ApplicationFiles","description":"File attachments for an application."},"ApplicationInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"application_id":{"type":"string","title":"Application Id"},"candidate_id":{"type":"string","title":"Candidate Id"},"vacancy_id":{"type":"string","title":"Vacancy Id"},"files":{"anyOf":[{"$ref":"#/components/schemas/ApplicationFiles"},{"type":"null"}]}},"type":"object","required":["application_id","candidate_id","vacancy_id"],"title":"ApplicationInput","description":"Input model for creating/updating applications.\n\nUsed for:\n- POST /applications (create)\n- PUT /applications/{id} (update)\n- Webhook payloads"},"Body_upload_file_v1_uploads_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_upload_file_v1_uploads_post"},"CalendarConnectRequest":{"properties":{"calendar_provider":{"$ref":"#/components/schemas/CalendarProvider","description":"Calendar provider to connect (google or microsoft)"},"return_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Return Url","description":"URL to redirect the user after OAuth completes"}},"type":"object","required":["calendar_provider","return_url"],"title":"CalendarConnectRequest","description":"Request to generate a calendar OAuth connection URL."},"CalendarConnectResponse":{"properties":{"oauth_url":{"type":"string","title":"Oauth Url","description":"URL to redirect the user to for calendar OAuth flow"}},"type":"object","required":["oauth_url"],"title":"CalendarConnectResponse","description":"Response containing the OAuth URL for calendar connection."},"CalendarProvider":{"type":"string","enum":["google","microsoft"],"title":"CalendarProvider","description":"Supported calendar providers for OAuth connection."},"CalendarSettingsUpdateRequest":{"properties":{"recording_setting":{"$ref":"#/components/schemas/RecordingSetting","description":"Recording behavior for calendar meetings"}},"type":"object","required":["recording_setting"],"title":"CalendarSettingsUpdateRequest","description":"Request to update calendar recording settings."},"Candidate":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"candidate_id":{"type":"string","title":"Candidate Id"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"email":{"type":"string","format":"email","title":"Email"},"phone_number":{"anyOf":[{"type":"string","description":"E.164 formatted phone number (e.g., +16502530000)"},{"type":"null"}],"title":"Phone Number"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Middle Name"},"name_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Prefix"},"nick_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nick Name"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Of Birth"},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nationality"},"marital_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marital Status"},"ethnicity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ethnicity"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"secondary_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secondary Address"},"linked_in":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linked In"},"preferred_contact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Contact"},"occupation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occupation"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"years_of_experience":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Years Of Experience"},"work_history":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work History"},"work_authorized":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Work Authorized"},"skill_set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skill Set"},"highest_degree":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Highest Degree"},"education":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Education"},"certifications":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certifications"},"job_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Category"},"job_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Name"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"desired_locations":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desired Locations"},"employment_preference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employment Preference"},"employee_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employee Type"},"date_available":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Available"},"date_available_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Available End"},"notice_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice Period"},"salary_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Salary Range"},"current_employment_conditions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Employment Conditions"},"has_car":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Car"},"drivers_license":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Drivers License"},"will_relocate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Will Relocate"},"willingness_to_travel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Willingness To Travel"},"max_commute_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Max Commute Time"},"max_travel_percentage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Max Travel Percentage"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"reason_for_leaving":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason For Leaving"}},"type":"object","required":["candidate_id","first_name","last_name","email"],"title":"Candidate","description":"Full candidate profile for retrieval operations.\n\nThis model extends CandidateBase with fields from ZeroWasteCandidateProfile\n(carv-ai), containing all extracted information about a candidate.\n\nUsed for:\n- GET /candidates (list)\n- GET /candidates/{id} (retrieve)\n- Outgoing webhook payloads"},"CandidateFiles":{"properties":{"resume":{"anyOf":[{"$ref":"#/components/schemas/FileReference"},{"type":"null"}]}},"type":"object","title":"CandidateFiles","description":"File attachments for a candidate."},"CandidateInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"candidate_id":{"type":"string","title":"Candidate Id"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"email":{"type":"string","format":"email","title":"Email"},"phone_number":{"anyOf":[{"type":"string","description":"E.164 formatted phone number (e.g., +16502530000)"},{"type":"null"}],"title":"Phone Number"},"files":{"anyOf":[{"$ref":"#/components/schemas/CandidateFiles"},{"type":"null"}]}},"type":"object","required":["candidate_id","first_name","last_name","email"],"title":"CandidateInput","description":"Input model for creating/updating candidates.\n\nThis is the simple model used for:\n- POST /candidates (create)\n- PUT /candidates/{id} (update)\n- Webhook payloads"},"ContentOutput":{"properties":{"content":{"type":"string","title":"Content","description":"AI-generated content"},"language_code":{"type":"string","title":"Language Code","description":"Language of the content (e.g., 'en')"},"format":{"type":"string","title":"Format","description":"Content format (e.g., 'text/plain', 'text/markdown')"}},"type":"object","required":["content","language_code","format"],"title":"ContentOutput","description":"AI-generated content output with metadata."},"EmbedUrlRequest":{"properties":{"candidate_id":{"type":"string","maxLength":255,"minLength":1,"title":"Candidate Id","description":"ATS candidate ID to generate embed URL for"}},"type":"object","required":["candidate_id"],"title":"EmbedUrlRequest","description":"Request body for generating an embeddable candidate URL."},"EmbedUrlResponse":{"properties":{"embed_url":{"type":"string","title":"Embed Url","description":"Full URL to embed in an iframe, includes auth token"},"expires_in":{"type":"integer","title":"Expires In","description":"Token validity in seconds (1 hour, fixed by Firebase SDK)."}},"type":"object","required":["embed_url","expires_in"],"title":"EmbedUrlResponse","description":"Response containing the embeddable URL and token metadata."},"EntityDeletedData":{"properties":{"entity_id":{"type":"string","title":"Entity Id","description":"ID of the deleted entity"}},"type":"object","required":["entity_id"],"title":"EntityDeletedData","description":"Data payload for entity deletion events."},"FileReference":{"properties":{"carv_file_id":{"type":"string","format":"uuid","title":"Carv File Id","description":"CarvOS file identifier from POST /uploads"}},"type":"object","required":["carv_file_id"],"title":"FileReference","description":"Reference to a CarvOS-uploaded file for use in webhook payloads.\n\nFiles must be uploaded via POST /uploads first. The returned carv_file_id\nis then included in webhook payloads to reference the file."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MeetingMetadata":{"properties":{"platform":{"type":"string","title":"Platform","description":"Meeting platform (e.g., 'zoom', 'google_meet', 'teams')"},"meeting_url":{"type":"string","title":"Meeting Url","description":"Original meeting URL","default":""},"title":{"type":"string","title":"Title","description":"Meeting title"},"duration_seconds":{"type":"integer","title":"Duration Seconds","description":"Duration in seconds"},"participants":{"items":{"$ref":"#/components/schemas/ParticipantInfo"},"type":"array","title":"Participants","description":"List of participants"}},"type":"object","required":["platform","title","duration_seconds"],"title":"MeetingMetadata","description":"Meeting metadata."},"MeetingNotesReadyPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"meeting.notes_ready","title":"Event","default":"meeting.notes_ready"},"data":{"$ref":"#/components/schemas/NotesReadyData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"MeetingNotesReadyPayload","description":"Webhook sent when AI-generated meeting notes are complete.\n\nContains structured markdown notes with sections for key discussion points,\ncandidate questions, and action items."},"MeetingSummaryReadyPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"meeting.summary_ready","title":"Event","default":"meeting.summary_ready"},"data":{"$ref":"#/components/schemas/SummaryReadyData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"MeetingSummaryReadyPayload","description":"Webhook sent when AI-generated summary is complete.\n\nContains a 5-sentence summary in plain text (active voice, third person)."},"MeetingTranscriptReadyPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"meeting.transcript_ready","title":"Event","default":"meeting.transcript_ready"},"data":{"$ref":"#/components/schemas/TranscriptReadyData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"MeetingTranscriptReadyPayload","description":"Webhook sent when meeting transcript is ready (before AI processing).\n\nSent immediately after Recall.ai completes transcript processing."},"MemberCreateInput":{"properties":{"name":{"type":"string","title":"Name","description":"Member display name"},"email":{"type":"string","format":"email","title":"Email","description":"Member email address"}},"type":"object","required":["name","email"],"title":"MemberCreateInput","description":"Input for adding a member to a workspace.\n\nUsed by both the REST API and incoming webhooks. The ``user_id``\nand ``client_id`` come from the header/URL (REST) or\n``WebhookPayloadBase`` (webhook)."},"MemberCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"member.created","title":"Event","default":"member.created"},"member":{"$ref":"#/components/schemas/MemberCreateInput"}},"type":"object","required":["event_id","client_id","user_id","member"],"title":"MemberCreatedPayload","description":"Payload for member.created webhook events."},"MemberDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id"},"event":{"type":"string","const":"member.deleted","title":"Event","default":"member.deleted"}},"type":"object","required":["event_id","client_id","user_id"],"title":"MemberDeletedPayload","description":"Payload for member.deleted webhook events (not yet consumed downstream)."},"NotesReadyData":{"properties":{"meeting_id":{"type":"string","title":"Meeting Id","description":"Carv meeting identifier"},"application_id":{"type":"string","title":"Application Id","description":"ATS application identifier"},"vacancy_id":{"type":"string","title":"Vacancy Id","description":"ATS vacancy identifier"},"candidate_id":{"type":"string","title":"Candidate Id","description":"ATS candidate identifier"},"meeting_metadata":{"$ref":"#/components/schemas/MeetingMetadata"},"notes":{"$ref":"#/components/schemas/ContentOutput"}},"type":"object","required":["meeting_id","application_id","vacancy_id","candidate_id","meeting_metadata","notes"],"title":"NotesReadyData","description":"Data payload for notes_ready event."},"OutgoingWebhookError":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error description"}},"type":"object","required":["message"],"title":"OutgoingWebhookError","description":"Error detail for failure webhook events."},"PartialApplicationInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"application_id":{"type":"string","title":"Application Id"},"candidate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Id"},"vacancy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vacancy Id"},"files":{"anyOf":[{"$ref":"#/components/schemas/ApplicationFiles"},{"type":"null"}]}},"type":"object","required":["application_id"],"title":"PartialApplicationInput"},"PartialCandidateInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"candidate_id":{"type":"string","title":"Candidate Id"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"phone_number":{"anyOf":[{"type":"string","description":"E.164 formatted phone number (e.g., +16502530000)"},{"type":"null"}],"title":"Phone Number"},"files":{"anyOf":[{"$ref":"#/components/schemas/CandidateFiles"},{"type":"null"}]}},"type":"object","required":["candidate_id"],"title":"PartialCandidateInput"},"PartialPartialApplicationInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"candidate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Id"},"vacancy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vacancy Id"},"files":{"anyOf":[{"$ref":"#/components/schemas/ApplicationFiles"},{"type":"null"}]}},"type":"object","title":"PartialPartialApplicationInput"},"PartialPartialCandidateInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"phone_number":{"anyOf":[{"type":"string","description":"E.164 formatted phone number (e.g., +16502530000)"},{"type":"null"}],"title":"Phone Number"},"files":{"anyOf":[{"$ref":"#/components/schemas/CandidateFiles"},{"type":"null"}]}},"type":"object","title":"PartialPartialCandidateInput"},"PartialPartialVacancyInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"locations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Address"},"type":"array"},{"type":"null"}],"title":"Locations"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","title":"PartialPartialVacancyInput"},"PartialVacancyInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"vacancy_id":{"type":"string","title":"Vacancy Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"locations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Address"},"type":"array"},{"type":"null"}],"title":"Locations"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["vacancy_id"],"title":"PartialVacancyInput"},"ParticipantInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Participant display name","default":""},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Participant email address (when available)"},"is_host":{"type":"boolean","title":"Is Host","description":"Whether participant is the meeting host","default":false}},"type":"object","title":"ParticipantInfo","description":"Meeting participant information."},"RecordingSetting":{"type":"string","enum":["record_all_meetings","record_internal_only","record_external_only","record_host_only","record_none"],"title":"RecordingSetting","description":"Recording behavior settings for calendar meetings."},"SummaryReadyData":{"properties":{"meeting_id":{"type":"string","title":"Meeting Id","description":"Carv meeting identifier"},"application_id":{"type":"string","title":"Application Id","description":"ATS application identifier"},"vacancy_id":{"type":"string","title":"Vacancy Id","description":"ATS vacancy identifier"},"candidate_id":{"type":"string","title":"Candidate Id","description":"ATS candidate identifier"},"meeting_metadata":{"$ref":"#/components/schemas/MeetingMetadata"},"summary":{"$ref":"#/components/schemas/ContentOutput"}},"type":"object","required":["meeting_id","application_id","vacancy_id","candidate_id","meeting_metadata","summary"],"title":"SummaryReadyData","description":"Data payload for summary_ready event."},"SystemStatusData":{"properties":{"status":{"type":"string","title":"Status","description":"System status (maintenance, degraded, operational)"},"message":{"type":"string","title":"Message","description":"Status message"},"scheduled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled At","description":"ISO 8601 timestamp for scheduled maintenance"}},"type":"object","required":["status","message"],"title":"SystemStatusData","description":"Data for system status events."},"SystemStatusPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"system.status","title":"Event","default":"system.status"},"data":{"$ref":"#/components/schemas/SystemStatusData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"SystemStatusPayload","description":"System status change notification.\n\nSent when CarvOS status changes (maintenance windows, degraded performance, etc.)."},"TranscriptContent":{"properties":{"content":{"type":"string","title":"Content","description":"Full transcript content"},"word_count":{"type":"integer","title":"Word Count","description":"Total word count"},"speaker_count":{"type":"integer","title":"Speaker Count","description":"Number of distinct speakers"},"language_code":{"type":"string","title":"Language Code","description":"Language of the transcript (e.g., 'en')"},"format":{"type":"string","title":"Format","description":"Content format (e.g., 'text/plain')"}},"type":"object","required":["content","word_count","speaker_count","language_code","format"],"title":"TranscriptContent","description":"Transcript content with metadata."},"TranscriptReadyData":{"properties":{"meeting_id":{"type":"string","title":"Meeting Id","description":"Carv meeting identifier"},"application_id":{"type":"string","title":"Application Id","description":"ATS application identifier"},"vacancy_id":{"type":"string","title":"Vacancy Id","description":"ATS vacancy identifier"},"candidate_id":{"type":"string","title":"Candidate Id","description":"ATS candidate identifier"},"meeting_metadata":{"$ref":"#/components/schemas/MeetingMetadata"},"transcript":{"$ref":"#/components/schemas/TranscriptContent"}},"type":"object","required":["meeting_id","application_id","vacancy_id","candidate_id","meeting_metadata","transcript"],"title":"TranscriptReadyData","description":"Data payload for transcript_ready event."},"UploadResponse":{"properties":{"carv_file_id":{"type":"string","format":"uuid","title":"Carv File Id","description":"Unique file identifier"},"file_name":{"type":"string","title":"File Name","description":"Original filename"},"content_type":{"type":"string","title":"Content Type","description":"Detected MIME type (magic bytes, validated against upload extension allowlist)."},"file_size":{"type":"integer","exclusiveMinimum":0.0,"title":"File Size","description":"File size in bytes"},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At","description":"When the file was uploaded"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the staged file will be automatically deleted"}},"type":"object","required":["carv_file_id","file_name","content_type","file_size","uploaded_at","expires_at"],"title":"UploadResponse","description":"Response returned after successful file upload."},"Vacancy":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"vacancy_id":{"type":"string","title":"Vacancy Id"},"title":{"type":"string","title":"Title"},"locations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Address"},"type":"array"},{"type":"null"}],"title":"Locations"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["vacancy_id","title"],"title":"Vacancy","description":"A vacancy stored in CarvOS.\n\nReturned when listing or retrieving vacancies."},"VacancyInput":{"properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created in the ATS. Defaults to now if not provided."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated in the ATS. Defaults to now if not provided."},"vacancy_id":{"type":"string","title":"Vacancy Id"},"title":{"type":"string","title":"Title"},"locations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Address"},"type":"array"},{"type":"null"}],"title":"Locations"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["vacancy_id","title"],"title":"VacancyInput","description":"A vacancy to create or update in CarvOS.\n\nInclude only the fields your ATS provides — everything except\n`vacancy_id` and `title` is optional."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Processing status, always 'accepted' for successfully received events.","default":"accepted"},"message":{"type":"string","title":"Message","description":"Human-readable confirmation message.","default":"Event accepted for processing"},"event":{"type":"string","title":"Event","description":"The event type that was accepted (e.g., 'candidate.created')."},"reference_id":{"type":"string","title":"Reference Id","description":"CarvOS-generated correlation ID for tracking this request."}},"type":"object","required":["event","reference_id"],"title":"WebhookResponse","description":"Standard response for accepted webhook events."},"WebhookTestData":{"properties":{"test":{"type":"boolean","const":true,"title":"Test","default":true},"message":{"type":"string","title":"Message","description":"Test message"}},"type":"object","required":["message"],"title":"WebhookTestData","description":"Data for webhook test events."},"WebhookTestPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"webhook.test","title":"Event","default":"webhook.test"},"data":{"$ref":"#/components/schemas/WebhookTestData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"WebhookTestPayload","description":"Test webhook for endpoint verification.\n\nSent when an ATS requests a test delivery to verify their endpoint is\ncorrectly configured to receive outgoing webhooks."},"WorkspaceCreateInput":{"properties":{"name":{"type":"string","title":"Name","description":"Workspace display name"},"admin_name":{"type":"string","title":"Admin Name","description":"Display name of the initial admin user"},"admin_email":{"type":"string","format":"email","title":"Admin Email","description":"Email of the initial admin user"}},"type":"object","required":["name","admin_name","admin_email"],"title":"WorkspaceCreateInput","description":"Input for creating a workspace.\n\nUsed by both the REST API and incoming webhooks. The ``client_id``\ncomes from the header (REST) or ``WebhookPayloadBase`` (webhook)."},"WorkspaceCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"workspace.created","title":"Event","default":"workspace.created"},"workspace":{"$ref":"#/components/schemas/WorkspaceCreateInput"}},"type":"object","required":["event_id","client_id","user_id","workspace"],"title":"WorkspaceCreatedPayload","description":"Payload for workspace.created webhook events."},"WorkspaceDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"workspace.deleted","title":"Event","default":"workspace.deleted"}},"type":"object","required":["event_id","client_id","user_id"],"title":"WorkspaceDeletedPayload","description":"Payload for workspace.deleted webhook events (not yet consumed downstream)."},"WorkspaceMemberAddedData":{"properties":{"user_id":{"type":"string","title":"User Id","description":"ATS user identifier"}},"type":"object","required":["user_id"],"title":"WorkspaceMemberAddedData","description":"Data payload for workspace member added events."},"WorkspaceMemberAddedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"workspace.member_added","title":"Event","default":"workspace.member_added"},"data":{"$ref":"#/components/schemas/WorkspaceMemberAddedData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"WorkspaceMemberAddedPayload","description":"Sent when a new member is added to a workspace.\n\nContains only the ATS user identifier of the added member."},"WorkspaceProvisionedData":{"properties":{"name":{"type":"string","title":"Name","description":"Workspace display name"},"admin_user_id":{"type":"string","title":"Admin User Id","description":"ATS user ID of the workspace admin"}},"type":"object","required":["name","admin_user_id"],"title":"WorkspaceProvisionedData","description":"Data payload for workspace provisioned events."},"WorkspaceProvisionedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"workspace.provisioned","title":"Event","default":"workspace.provisioned"},"data":{"$ref":"#/components/schemas/WorkspaceProvisionedData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"WorkspaceProvisionedPayload","description":"Sent when a workspace is fully provisioned and ready for use.\n\nContains the workspace name and the admin user who initiated provisioning."},"WorkspaceUpdateInput":{"properties":{"name":{"type":"string","title":"Name","description":"Updated workspace display name"}},"type":"object","required":["name"],"title":"WorkspaceUpdateInput","description":"Input for updating a workspace (not yet consumed downstream)."},"WorkspaceUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"workspace.updated","title":"Event","default":"workspace.updated"},"workspace":{"$ref":"#/components/schemas/WorkspaceUpdateInput"}},"type":"object","required":["event_id","client_id","user_id","workspace"],"title":"WorkspaceUpdatedPayload","description":"Payload for workspace.updated webhook events (not yet consumed downstream)."},"carvos__domains__applications__incoming_webhooks__models__ApplicationCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"application.created","title":"Event","default":"application.created"},"application":{"$ref":"#/components/schemas/ApplicationInput"}},"type":"object","required":["event_id","client_id","user_id","application"],"title":"ApplicationCreatedPayload","description":"Payload for application.created webhook events."},"carvos__domains__applications__incoming_webhooks__models__ApplicationDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"application.deleted","title":"Event","default":"application.deleted"},"application_id":{"type":"string","title":"Application Id"}},"type":"object","required":["event_id","client_id","user_id","application_id"],"title":"ApplicationDeletedPayload","description":"Payload for application.deleted webhook events."},"carvos__domains__applications__incoming_webhooks__models__ApplicationUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"application.updated","title":"Event","default":"application.updated"},"application":{"$ref":"#/components/schemas/PartialApplicationInput"}},"type":"object","required":["event_id","client_id","user_id","application"],"title":"ApplicationUpdatedPayload","description":"Payload for application.updated webhook events."},"carvos__domains__applications__models__ApplicationCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"application.created","title":"Event","default":"application.created"},"data":{"$ref":"#/components/schemas/Application"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"ApplicationCreatedPayload","description":"Sent when CarvOS finishes processing a new application.\n\nContains the application data. Analysis field may be null if\nAI processing is still in progress."},"carvos__domains__applications__models__ApplicationDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"application.deleted","title":"Event","default":"application.deleted"},"data":{"$ref":"#/components/schemas/EntityDeletedData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"ApplicationDeletedPayload","description":"Sent when an application is deleted.\n\nContains only the identifier of the deleted application."},"carvos__domains__applications__models__ApplicationUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"application.updated","title":"Event","default":"application.updated"},"data":{"$ref":"#/components/schemas/Application"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"ApplicationUpdatedPayload","description":"Sent when CarvOS updates application data.\n\nCommonly triggered when:\n- AI analysis completes (analysis field populated)\n- Files are attached or updated"},"carvos__domains__candidates__incoming_webhooks__models__CandidateCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"candidate.created","title":"Event","default":"candidate.created"},"candidate":{"$ref":"#/components/schemas/CandidateInput"}},"type":"object","required":["event_id","client_id","user_id","candidate"],"title":"CandidateCreatedPayload","description":"Payload for candidate.created webhook events."},"carvos__domains__candidates__incoming_webhooks__models__CandidateDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"candidate.deleted","title":"Event","default":"candidate.deleted"},"candidate_id":{"type":"string","title":"Candidate Id"}},"type":"object","required":["event_id","client_id","user_id","candidate_id"],"title":"CandidateDeletedPayload","description":"Payload for candidate.deleted webhook events."},"carvos__domains__candidates__incoming_webhooks__models__CandidateUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"candidate.updated","title":"Event","default":"candidate.updated"},"candidate":{"$ref":"#/components/schemas/PartialCandidateInput"}},"type":"object","required":["event_id","client_id","user_id","candidate"],"title":"CandidateUpdatedPayload","description":"Payload for candidate.updated webhook events."},"carvos__domains__candidates__models__CandidateCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"candidate.created","title":"Event","default":"candidate.created"},"data":{"$ref":"#/components/schemas/Candidate"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"CandidateCreatedPayload","description":"Sent when CarvOS finishes processing a new candidate.\n\nContains the full normalized candidate profile with all extracted data."},"carvos__domains__candidates__models__CandidateDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"candidate.deleted","title":"Event","default":"candidate.deleted"},"data":{"$ref":"#/components/schemas/EntityDeletedData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"CandidateDeletedPayload","description":"Sent when a candidate is deleted.\n\nContains only the identifier of the deleted candidate."},"carvos__domains__candidates__models__CandidateUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"candidate.updated","title":"Event","default":"candidate.updated"},"data":{"$ref":"#/components/schemas/Candidate"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"CandidateUpdatedPayload","description":"Sent when CarvOS updates candidate data.\n\nContains the updated candidate profile with all current data."},"carvos__domains__vacancies__incoming_webhooks__models__VacancyCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"vacancy.created","title":"Event","default":"vacancy.created"},"vacancy":{"$ref":"#/components/schemas/VacancyInput"}},"type":"object","required":["event_id","client_id","user_id","vacancy"],"title":"VacancyCreatedPayload","description":"Payload for vacancy.created webhook events."},"carvos__domains__vacancies__incoming_webhooks__models__VacancyDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"vacancy.deleted","title":"Event","default":"vacancy.deleted"},"vacancy_id":{"type":"string","title":"Vacancy Id"}},"type":"object","required":["event_id","client_id","user_id","vacancy_id"],"title":"VacancyDeletedPayload","description":"Payload for vacancy.deleted webhook events."},"carvos__domains__vacancies__incoming_webhooks__models__VacancyUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for deduplication"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier (maps to workspace)"},"user_id":{"type":"string","title":"User Id","description":"ATS user identifier (maps to member)"},"event":{"type":"string","const":"vacancy.updated","title":"Event","default":"vacancy.updated"},"vacancy":{"$ref":"#/components/schemas/PartialVacancyInput"}},"type":"object","required":["event_id","client_id","user_id","vacancy"],"title":"VacancyUpdatedPayload","description":"Payload for vacancy.updated webhook events."},"carvos__domains__vacancies__models__VacancyCreatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"vacancy.created","title":"Event","default":"vacancy.created"},"data":{"$ref":"#/components/schemas/Vacancy"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"VacancyCreatedPayload","description":"Sent when CarvOS finishes processing a new vacancy.\n\nContains the full vacancy data with all normalized fields."},"carvos__domains__vacancies__models__VacancyDeletedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"vacancy.deleted","title":"Event","default":"vacancy.deleted"},"data":{"$ref":"#/components/schemas/EntityDeletedData"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"VacancyDeletedPayload","description":"Sent when a vacancy is deleted.\n\nContains only the identifier of the deleted vacancy."},"carvos__domains__vacancies__models__VacancyUpdatedPayload":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier for idempotency"},"client_id":{"type":"string","title":"Client Id","description":"ATS client identifier"},"reference_id":{"type":"string","title":"Reference Id","description":"Correlation ID tying this outgoing webhook back to the originating async-ingress request. Matches the ``reference_id`` returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion. Include it in any support request so we can trace the full flow end-to-end."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"ISO 8601 timestamp when event occurred"},"status":{"type":"string","enum":["success","failure"],"title":"Status","description":"Event status","default":"success"},"error":{"anyOf":[{"$ref":"#/components/schemas/OutgoingWebhookError"},{"type":"null"}],"description":"Error detail on failure"},"event":{"type":"string","const":"vacancy.updated","title":"Event","default":"vacancy.updated"},"data":{"$ref":"#/components/schemas/Vacancy"}},"type":"object","required":["event_id","client_id","reference_id","data"],"title":"VacancyUpdatedPayload","description":"Sent when CarvOS updates vacancy data.\n\nContains the updated vacancy with all current data."}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"API key for authentication. Provide your API key in the X-API-Key header.","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Workspaces","description":"Manage workspaces and their members for ATS clients."},{"name":"Applications","description":"Manage applications. Supports both thin (ID references) and fat (embedded data) payload formats for flexible ATS integration."},{"name":"Candidates","description":"Access candidate profiles with normalized data from various ATS providers."},{"name":"Vacancies","description":"Access vacancy requisitions with normalized data including compensation, locations, and requirements."},{"name":"Meetings","description":"Calendar integration and meeting management. Connect calendars via OAuth and manage meeting recordings."},{"name":"Uploads","description":"Binary file upload endpoint. Upload files first to receive a reference ID, then include the reference in subsequent API calls."},{"name":"Embeds","description":"Generate embeddable URLs for ATS systems to display candidate profiles in iframes."},{"name":"Incoming Webhooks","description":"Per-ATS webhook endpoints for receiving events from ATS systems. Each ATS has a dedicated endpoint at `/v1/webhooks/{ats_id}` with per-ATS webhook secrets. Payloads use a discriminated union on the `event` field for automatic routing to typed handlers. All requests require HMAC-SHA256 signature verification. See **Webhook Signature Verification** above for details."}],"x-tagGroups":[{"name":"Organization","tags":["Workspaces"]},{"name":"Recruiting","tags":["Applications","Candidates","Vacancies"]},{"name":"Collaboration","tags":["Meetings","Uploads"]},{"name":"Integration","tags":["Embeds","Incoming Webhooks"]}]}