{ "openapi": "3.1.0", "info": { "title": "Stardex API (v1)", "version": "1.0.0", "description": "Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows." }, "servers": [ { "url": "https://api.stardex.ai", "description": "Production API server" } ], "tags": [ { "name": "Persons", "description": "Manage person records — contacts, work history, and custom fields." }, { "name": "Jobs", "description": "Manage job postings — pipeline stages, team members, and custom fields." }, { "name": "Candidates", "description": "Manage candidate records and pipeline stage transitions." }, { "name": "Companies", "description": "Browse and retrieve company records." }, { "name": "Lists", "description": "Create, search, and retrieve saved person and company lists." }, { "name": "Person Activities", "description": "Create and manage activity records (notes, emails, meetings) for persons." }, { "name": "Team Members", "description": "List team members for use in search filters and assignments." }, { "name": "Custom Fields", "description": "Retrieve custom field definitions and tag options for search filters." }, { "name": "Campaigns", "description": "Create and edit email campaigns, enroll people through enrollment batches, and manage who is enrolled." } ], "components": { "schemas": { "ActivityReportRequest": { "type": "object", "properties": { "segment_by": { "type": "string", "enum": [ "team_member", "job", "company" ], "description": "Dimension to group the report by:\n- `team_member` — one segment per recruiter\n- `job` — one segment per job\n- `company` — one segment per client/organization company" }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly", "custom" ], "default": "custom", "description": "Convenience preset that derives the date range when `date_from` / `date_to` are omitted:\n- `daily` — the start of today through now\n- `weekly` — the trailing 7 days through now\n- `monthly` — the trailing 30 days through now\n- `custom` — use the explicit `date_from` / `date_to` values (required when `custom`)." }, "date_from": { "type": "string", "format": "date-time", "description": "Start of the report window (ISO 8601). Required when `period=custom`. Applied to `created_at` for activities, candidates, tasks, and `entered_at` for stage changes / `enrolled_at` for campaign enrollments. Custom windows are limited to 2 years." }, "date_to": { "type": "string", "format": "date-time", "description": "End of the report window (ISO 8601). Required when `period=custom`. Custom windows are limited to 2 years." }, "team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "description": "Optional recruiter UUIDs to narrow the report. Affects both the aggregate totals and per-segment rows. Maximum 200 IDs. Get IDs from `GET /v1/team-members`." }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "description": "Optional job UUIDs to narrow the report. Affects both the aggregate totals and per-segment rows. Maximum 200 IDs." }, "organization_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "description": "Optional client/company UUIDs to narrow the report. When provided, only activity tied to jobs at these companies (or directly to these client companies) is counted. Maximum 200 IDs." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "pipeline_snapshot", "job_breakdown", "crm_activities" ] }, "description": "Optional sections to embed per segment. Values:\n- `pipeline_snapshot` — current candidate count per pipeline stage (for `job` / `company` segments)\n- `job_breakdown` — per-job candidates-sourced breakdown (for `team_member` segments)\n- `crm_activities` — fold `client_activities` and `client_status_changes` into the company segment metrics" } }, "required": [ "segment_by" ] }, "ActivityReportResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ActivityReportData" } }, "required": [ "success", "data" ] }, "ActivityReportData": { "type": "object", "properties": { "segment_by": { "type": "string", "enum": [ "team_member", "job", "company" ], "description": "Echo of the request `segment_by`." }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly", "custom" ], "description": "Echo of the request `period`." }, "date_from": { "type": "string", "description": "Resolved start of the report window (ISO 8601). Computed from `period` when not supplied." }, "date_to": { "type": "string", "description": "Resolved end of the report window (ISO 8601)." }, "aggregate": { "allOf": [ { "$ref": "#/components/schemas/ActivityReportMetrics" }, { "description": "Totals across the entire selection (every segment combined). Useful as the report header." } ] }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityReportSegment" }, "description": "Per-segment rows. Empty when the selection produced no activity in the window." } }, "required": [ "segment_by", "period", "date_from", "date_to", "aggregate", "segments" ] }, "ActivityReportMetrics": { "type": "object", "properties": { "activities_by_type": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityReportActivityCount" }, "description": "Activity counts grouped by `person_activities.type`. Excludes `candidate_summary` and `primary_note`. Includes a synthetic `campaign_enrollment` row when relevant." }, "candidates_sourced": { "type": "integer", "description": "Number of `candidates` created in the window. For team-member segments this is filtered to `sourced_by_team_member = member`." }, "stage_changes": { "type": "integer", "description": "Number of `candidate_pipeline_statuses` rows entered in the window (every pipeline move, including rejections)." }, "rejections": { "type": "integer", "description": "Subset of stage changes where `stage_change_reason_id` is set (i.e. the move was a rejection)." }, "enrollments": { "type": "integer", "description": "Campaign enrollments created in the window (`sequence_enrollments`)." }, "tasks": { "type": "integer", "description": "Tasks created in the window. For team-member segments this counts tasks the member owns (via `task_owners`)." }, "stage_changes_by_stage": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityReportStageChangeBreakdown" }, "description": "Per-stage breakdown of stage changes. Stages are keyed by the global `pipeline_stages.id` so the same logical stage collapses across jobs." }, "pipeline_snapshot": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityReportPipelineSnapshotEntry" }, "description": "Current candidate distribution across pipeline stages (snapshot, not date-filtered). Only present for `job` / `company` segments when `include` contains `pipeline_snapshot`." }, "job_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityReportJobBreakdownEntry" }, "description": "Per-job sourcing breakdown for this segment. Only present for `team_member` segments when `include` contains `job_breakdown`." } }, "required": [ "activities_by_type", "candidates_sourced", "stage_changes", "rejections", "enrollments", "tasks", "stage_changes_by_stage" ] }, "ActivityReportActivityCount": { "type": "object", "properties": { "type": { "type": "string", "description": "Activity type key (e.g. `secondary_note`, `email`, `linkedin_message`, or a team-defined custom key). The synthetic key `campaign_enrollment` is used for the campaign enrollments rollup." }, "label": { "type": "string", "description": "Human-friendly display label. Falls back to the team-configured `person_activity_types.name` then to a title-cased version of the key." }, "count": { "type": "integer", "description": "Number of activities of this type in the window." } }, "required": [ "type", "label", "count" ] }, "ActivityReportStageChangeBreakdown": { "type": "object", "properties": { "pipeline_stage_id": { "type": "string", "format": "uuid", "description": "Global `pipeline_stages.id`. The same logical stage (e.g. \"Interview\") collapses across jobs onto a single row." }, "stage_name": { "type": "string", "description": "Stage display name." }, "stage_color": { "type": "string", "description": "Stage display color (hex)." }, "global_order": { "type": "integer", "description": "Position of this stage in the global pipeline ordering. Use to sort funnel rows." }, "count": { "type": "integer", "description": "Number of stage changes into this stage in the window." } }, "required": [ "pipeline_stage_id", "stage_name", "stage_color", "global_order", "count" ] }, "ActivityReportPipelineSnapshotEntry": { "type": "object", "properties": { "pipeline_stage_id": { "type": "string", "format": "uuid", "description": "Global `pipeline_stages.id`." }, "stage_name": { "type": "string", "description": "Stage display name." }, "stage_color": { "type": "string", "description": "Stage display color (hex)." }, "global_order": { "type": "integer", "description": "Stage position in the global ordering." }, "candidate_count": { "type": "integer", "description": "Current candidate count in this stage (snapshot — NOT filtered by date)." } }, "required": [ "pipeline_stage_id", "stage_name", "stage_color", "global_order", "candidate_count" ] }, "ActivityReportJobBreakdownEntry": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "job_title": { "type": "string", "description": "Job title." }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client/company UUID linked to the job." }, "company_name": { "type": [ "string", "null" ], "description": "Client/company display name." }, "candidates_sourced": { "type": "integer", "description": "Candidates sourced into this job by the segment owner in the window." } }, "required": [ "job_id", "job_title", "company_id", "company_name", "candidates_sourced" ] }, "ActivityReportSegment": { "type": "object", "properties": { "segment_type": { "type": "string", "enum": [ "team_member", "job", "company" ], "description": "Echoes the request `segment_by` so each row is self-describing." }, "id": { "type": "string", "format": "uuid", "description": "Identity of the segment — team_member.id, jobs.id, or organization_companies.id depending on `segment_type`." }, "name": { "type": "string", "description": "Display name — \"First Last\" for team members, the job title for jobs, or the company name for companies." }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "For `job` segments: the client/company UUID linked to the job. Null for other segment types." }, "company_name": { "type": [ "string", "null" ], "description": "For `job` segments: the client/company display name. Null for other segment types." }, "metrics": { "allOf": [ { "$ref": "#/components/schemas/ActivityReportMetrics" }, { "description": "All activity counts and breakdowns for this segment in the window." } ] } }, "required": [ "segment_type", "id", "name", "company_id", "company_name", "metrics" ] }, "AutomationsSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Case-insensitive substring match on the automation name." }, "is_enabled": { "type": "boolean", "description": "Filter by whether the automation is enabled." }, "is_archived": { "type": "boolean", "default": false, "description": "Filter by archive status. Defaults to false so archived automations are hidden." }, "trigger_type": { "type": "string", "enum": [ "schedule", "candidate_status_changed", "job_status_changed", "job_created", "deal_status_changed" ], "description": "Filter by trigger kind." }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at", "name" ], "default": "created_at", "description": "Column to sort by. Defaults to created_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc." } } }, "AutomationsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationSummary" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "AutomationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Automation UUID." }, "name": { "type": "string", "description": "Display name." }, "is_enabled": { "type": "boolean", "description": "Whether new fires are enqueued." }, "is_archived": { "type": "boolean", "description": "Whether the automation is archived." }, "runs_on_api_changes": { "type": "boolean", "description": "When true, changes made through the API or MCP (including Zapier) also start this automation. Off by default, because one API call can change hundreds of records and each change starts a run." }, "trigger_type": { "type": "string", "enum": [ "schedule", "candidate_status_changed", "job_status_changed", "job_created", "deal_status_changed" ], "description": "Trigger kind." }, "action_count": { "type": "integer", "description": "Number of actions on this automation." }, "action_types": { "type": "array", "items": { "type": "string", "enum": [ "send_email", "add_note", "agent_instructions", "delay", "create_task" ] }, "description": "Distinct action types, in position order." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." } }, "required": [ "id", "name", "is_enabled", "is_archived", "runs_on_api_changes", "trigger_type", "action_count", "action_types", "created_at", "updated_at" ] }, "AutomationTriggerTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "success", "data" ] }, "AutomationActionTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "success", "data" ] }, "AutomationRunStatusesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "success", "data" ] }, "AutomationByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Automation" } }, "required": [ "success", "data" ] }, "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Automation UUID." }, "name": { "type": "string", "description": "Display name." }, "is_enabled": { "type": "boolean", "description": "Whether new fires are enqueued." }, "is_archived": { "type": "boolean", "description": "Whether the automation is archived." }, "runs_on_api_changes": { "type": "boolean", "description": "When true, changes made through the API or MCP (including Zapier) also start this automation. Off by default, because one API call can change hundreds of records and each change starts a run." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The automation's creator: the team member who created it, or the admin who took it over by editing it after the creator left. Emails from a mailbox and agent steps act as this member. Null when the automation was created with an API key." }, "trigger": { "$ref": "#/components/schemas/AutomationTrigger" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationAction" }, "description": "Ordered actions. At least one is required on create." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." } }, "required": [ "id", "name", "is_enabled", "is_archived", "runs_on_api_changes", "created_by", "trigger", "actions", "created_at", "updated_at" ] }, "AutomationTrigger": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "schedule" ], "description": "Fire on a recurring calendar schedule." }, "rrule": { "type": "string", "pattern": "^FREQ=", "description": "RRULE body. FREQ=DAILY, or FREQ=WEEKLY with BYDAY. Optional INTERVAL, BYHOUR, BYMINUTE, UNTIL. BYHOUR and BYMINUTE take a single value, so a schedule runs once on each day it runs. MONTHLY and YEARLY are not supported.", "example": "FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0" }, "dtstart": { "type": "string", "description": "ISO 8601 series origin used with timezone when expanding the RRULE." }, "timezone": { "type": "string", "minLength": 1, "description": "IANA timezone used to expand the RRULE (e.g. Europe/Madrid)." }, "next_run_at": { "type": "string", "description": "Next scheduled fire. Computed by the server from rrule, dtstart, and timezone. Ignored on write." } }, "required": [ "type", "rrule", "dtstart", "timezone" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "candidate_status_changed" ], "description": "Fire when a candidate lands on a pipeline stage." }, "pipeline_stage_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Pipeline stage UUIDs to match. The automation fires when a candidate moves to any of them. Leave empty, with match_rejection_stages off, to fire on every stage change. Get IDs from GET /v1/jobs/pipeline-stages." }, "match_rejection_stages": { "type": "boolean", "description": "Also fire when a candidate moves to any rejection stage, including rejection stages added later. Defaults to false." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "job_status_changed" ], "description": "Fire when a job lands on a status." }, "job_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job status UUID to match. Null or omitted means any job status change. Get IDs from GET /v1/jobs/statuses." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "job_created" ], "description": "Fire when a new active job is created. Archived jobs, deleted jobs, and onboarding sample data are skipped." }, "organization_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client (company) UUID to match. Null or omitted means a job for any client. Get IDs from POST /v1/companies/search." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "deal_status_changed" ], "description": "Fire when a deal moves to a status. Creating a deal does not fire it." }, "deal_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Deal status UUID to match. Null or omitted means any deal status change. Get IDs from GET /v1/deals/statuses." } }, "required": [ "type" ] } ] }, "AutomationAction": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Action UUID. Assigned on create; ignored when replacing the action list." }, "position": { "type": "integer", "minimum": 1, "description": "1-based order. Assigned from array order on write." }, "action_type": { "type": "string", "enum": [ "send_email" ] }, "recipient_type": { "type": "string", "enum": [ "candidate", "team_member", "team_members", "job_owner", "client_contacts" ], "description": "Who receives the email. team_members emails every teammate in payload.team_member_ids and every address in payload.email_addresses (at least one between them); team_member is the older single-teammate form. candidate needs a candidate trigger. job_owner emails every owner of the job and needs a candidate or job trigger. client_contacts emails every client contact of the job, or of the deal on a deal trigger. candidate and client_contacts are sent from payload.sender's mailbox and skip anyone unsubscribed, marked do not contact or with a bounced address; a candidate is only emailed at a personal address and is skipped if they only have a work email; the same automation does not email the same address about the same candidate and search (or deal) twice within 24 hours; team_members, team_member and job_owner get the email from Stardex, with replies going to the automation's creator." }, "team_member_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when recipient_type is team_member. Get IDs from GET /v1/team-members." }, "payload": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "description": "Email subject line. Supports the same {{variables}} as the body." }, "body": { "type": "string", "minLength": 1, "description": "Plain text email body. Blank lines start a new paragraph. Supports {{candidate_name}}, {{candidate_first_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}}, {{client_name}}, {{deal_name}}, {{deal_status_name}} and {{search_owner}} where the trigger provides them. On a schedule trigger, {{agent_output}} inserts the output of the nearest agent step before this email, formatted; the email then lists the records that step changed and ends with a footer linking to the run and the automation, and its subject ends with ' · ' and the date it was sent (for example 'Offers waiting · Aug 31'). When that step has no output, the email is skipped (result.code email_skipped). An email with {{agent_output}} can only go to the automation's creator and organization admins: recipient_type team_member or team_members, with no email_addresses. This is checked when the automation is saved and again when the email sends." }, "sender": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mailbox" ] }, "nylas_grant_id": { "type": "string", "format": "uuid", "description": "A connected mailbox the automation's creator owns or has shared access to." } }, "required": [ "kind", "nylas_grant_id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "job_owner" ], "description": "Send from the job owner's mailbox. The automation's creator must have access to it when the email is sent." } }, "required": [ "kind" ] } ], "description": "Which mailbox sends the email. Required when recipient_type is candidate or client_contacts. Emails to team members come from Stardex instead." }, "team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Teammates who receive the email when recipient_type is team_members. Get IDs from GET /v1/team-members." }, "email_addresses": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "Other addresses that receive the email when recipient_type is team_members, for example finance@yourfirm.com. They get it from Stardex, like teammates do." }, "include_signature": { "type": "boolean", "description": "Add the sending mailbox's signature to the end of the email. Only applies to candidate and client_contacts emails, which are sent from a mailbox. Defaults to false." } }, "required": [ "subject", "body" ] } }, "required": [ "action_type", "recipient_type", "payload" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Action UUID. Assigned on create; ignored when replacing the action list." }, "position": { "type": "integer", "minimum": 1, "description": "1-based order. Assigned from array order on write." }, "action_type": { "type": "string", "enum": [ "add_note" ] }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member recorded as the note author. Get IDs from GET /v1/team-members." }, "payload": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Note text added to the candidate. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, and {{client_name}}." } }, "required": [ "content" ] } }, "required": [ "action_type", "team_member_id", "payload" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Action UUID. Assigned on create; ignored when replacing the action list." }, "position": { "type": "integer", "minimum": 1, "description": "1-based order. Assigned from array order on write." }, "action_type": { "type": "string", "enum": [ "agent_instructions" ] }, "payload": { "type": "object", "properties": { "instructions": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Plain-English instructions for the agent, ideally with an example of the output. On a schedule trigger the agent follows them as the automation's creator, and a later email step can include its output as {{agent_output}}. On other triggers, or when the automation has no creator because it was created with an API key, the step is skipped when the automation runs (result.code agent_skipped). Agent steps are in early access; where they are not turned on, the step is saved and skipped (result.code not_implemented) and {{agent_output}} is rejected." }, "allow_update_records": { "type": "boolean", "description": "Let the agent create and update records, for example move candidates to another stage, update deals or add tasks and notes. Defaults to false, which keeps the agent read-only. Even when on, the agent cannot send email, enroll people in campaigns or sequences, run paid contact enrichment, change automations or team capacity settings, add, change or delete references, set preferred email addresses or phone numbers, mark email addresses as bounced or remove them, or change retainer packs, their retainer splits or referral partners, and it makes at most 2,000 changes in one batch." }, "allow_delete_records": { "type": "boolean", "description": "Let the agent delete, archive or remove records, for example archive a deal or remove people from a list. Defaults to false." }, "output_format": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "short_summary", "bullet_list", "table" ], "description": "short_summary: a few lines; bullet_list: one bullet per item; table: one row per item." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "custom" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 300, "description": "How the output should look, in your own words, for example \"One line per company, newest first\"." } }, "required": [ "kind", "text" ] }, { "type": "null" } ], "description": "How the agent formats its output. When set, it wins over any layout the instructions describe, except when there is nothing to list. Leave it out or set null to let the agent decide from the instructions." } }, "required": [ "instructions" ] } }, "required": [ "action_type", "payload" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Action UUID. Assigned on create; ignored when replacing the action list." }, "position": { "type": "integer", "minimum": 1, "description": "1-based order. Assigned from array order on write." }, "action_type": { "type": "string", "enum": [ "delay" ], "description": "Pause the run, then continue with the next action. Cannot be the last action." }, "payload": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "How many units to wait before the next action. Whole number, at least 1.", "example": 2 }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "description": "Unit for amount. A day is a fixed 24 hours.", "example": "days" } }, "required": [ "amount", "unit" ] } }, "required": [ "action_type", "payload" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Action UUID. Assigned on create; ignored when replacing the action list." }, "position": { "type": "integer", "minimum": 1, "description": "1-based order. Assigned from array order on write." }, "action_type": { "type": "string", "enum": [ "create_task" ], "description": "Create a task. It links to the candidate, job and deal from the trigger when there are any." }, "assignee_type": { "type": "string", "enum": [ "team_member", "job_owner", "deal_owner" ], "description": "Who the task is assigned to. job_owner assigns every owner of the job the run is about and is valid on candidate and job triggers. deal_owner assigns every owner of the deal and is valid on deal triggers." }, "team_member_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when assignee_type is team_member. Get IDs from GET /v1/team-members." }, "payload": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Task text. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}} and {{client_name}} where the trigger provides them." }, "task_type": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ], "description": "Task type, the same values as tasks elsewhere in Stardex." }, "due_in_days": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 7 ] } ], "description": "Days after the step runs that the task is due. 0 means the same day.", "example": 1 } }, "required": [ "content", "task_type", "due_in_days" ] } }, "required": [ "action_type", "assignee_type", "payload" ] } ] }, "AutomationUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name." }, "is_enabled": { "type": "boolean", "description": "Enable or disable new fires. In-flight runs still finish." }, "is_archived": { "type": "boolean", "description": "Archive or restore the automation." }, "runs_on_api_changes": { "type": "boolean", "description": "When true, changes made through the API or MCP (including Zapier) also start this automation. Off by default, because one API call can change hundreds of records and each change starts a run." }, "trigger": { "$ref": "#/components/schemas/AutomationTrigger" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationAction" }, "minItems": 1, "description": "Replace the full action list. Omit to leave existing actions unchanged." } } }, "AutomationUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Automation" } }, "required": [ "success", "data" ] }, "AutomationCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name (required)." }, "is_enabled": { "type": "boolean", "default": true, "description": "Whether the automation is enabled. Defaults to true." }, "runs_on_api_changes": { "type": "boolean", "default": false, "description": "When true, changes made through the API or MCP (including Zapier) also start this automation. Off by default, because one API call can change hundreds of records and each change starts a run. Defaults to false." }, "trigger": { "$ref": "#/components/schemas/AutomationTrigger" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationAction" }, "minItems": 1, "description": "Ordered actions. At least one is required." } }, "required": [ "name", "trigger", "actions" ] }, "AutomationCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Automation" } }, "required": [ "success", "data" ] }, "AutomationRunsSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "pending", "processing", "waiting", "completed", "failed", "skipped", "dead_letter" ] }, "description": "Filter by one or more run statuses." }, "trigger_type": { "type": "string", "enum": [ "schedule", "candidate_status_changed", "job_status_changed", "job_created", "deal_status_changed" ], "description": "Filter by the trigger that created the run." }, "person_id": { "type": "string", "format": "uuid", "description": "Filter to runs for one candidate (person)." }, "sort_by": { "type": "string", "enum": [ "created_at", "started_at", "finished_at" ], "default": "created_at", "description": "Column to sort by. Defaults to created_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc." } } }, "AutomationRunsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Run UUID." }, "automation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "waiting", "completed", "failed", "skipped", "dead_letter" ], "description": "`waiting` means the run is paused on a delay action, or waiting for an agent action to finish, until `resume_at`. `completed` means at least one action did work. `skipped` means the run finished without any action doing work, for example when the automation has no actions or every action was skipped, or it was turned off while waiting. `failed` will be retried; `dead_letter` will not." }, "attempts": { "type": "integer" }, "error_message": { "type": [ "string", "null" ] }, "trigger_type": { "type": "string", "enum": [ "schedule", "candidate_status_changed", "job_status_changed", "job_created", "deal_status_changed" ] }, "trigger_payload": { "type": [ "object", "null" ], "properties": { "candidate_id": { "type": "string", "format": "uuid" }, "person_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "old_pipeline_stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "new_pipeline_stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "old_job_status_id": { "type": [ "string", "null" ], "format": "uuid" }, "new_job_status_id": { "type": [ "string", "null" ], "format": "uuid" }, "old_deal_status_id": { "type": [ "string", "null" ], "format": "uuid" }, "new_deal_status_id": { "type": [ "string", "null" ], "format": "uuid" }, "job_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "For a \"new search created\" trigger, the status the record was created with." }, "organization_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "For a \"new search created\" trigger, the client the record was created for. Null when it has no client." }, "scheduled_for": { "type": "string" } } }, "change_source": { "type": [ "string", "null" ], "enum": [ "api", "mcp" ], "description": "api or mcp when the change that started this run was made through the API or MCP (including Zapier). Null for changes made in Stardex and for scheduled runs." }, "candidate_id": { "type": [ "string", "null" ], "format": "uuid" }, "person_id": { "type": [ "string", "null" ], "format": "uuid" }, "job_id": { "type": [ "string", "null" ], "format": "uuid" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The deal a deal status trigger fired for. Null for other triggers." }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "resume_at": { "type": [ "string", "null" ], "description": "When a waiting run continues. Null unless status is waiting." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRunStep" } } }, "required": [ "id", "automation_id", "status", "attempts", "error_message", "trigger_type", "trigger_payload", "change_source", "candidate_id", "person_id", "job_id", "deal_id", "started_at", "finished_at", "resume_at", "created_at", "updated_at" ] }, "AutomationRunStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Step UUID." }, "position": { "type": "integer", "description": "1-based action order." }, "action_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Source action UUID at enqueue time, if still present." }, "action_type": { "type": "string", "enum": [ "send_email", "add_note", "agent_instructions", "delay", "create_task" ] }, "action_config": { "type": "object", "properties": { "action_id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "action_type": { "type": "string", "enum": [ "send_email", "add_note", "agent_instructions", "delay", "create_task" ] }, "recipient_type": { "type": [ "string", "null" ], "enum": [ "candidate", "team_member", "team_members", "job_owner", "deal_owner", "client_contacts" ] }, "team_member_id": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "anyOf": [ { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "description": "Email subject line. Supports the same {{variables}} as the body." }, "body": { "type": "string", "minLength": 1, "description": "Plain text email body. Blank lines start a new paragraph. Supports {{candidate_name}}, {{candidate_first_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}}, {{client_name}}, {{deal_name}}, {{deal_status_name}} and {{search_owner}} where the trigger provides them. On a schedule trigger, {{agent_output}} inserts the output of the nearest agent step before this email, formatted; the email then lists the records that step changed and ends with a footer linking to the run and the automation, and its subject ends with ' · ' and the date it was sent (for example 'Offers waiting · Aug 31'). When that step has no output, the email is skipped (result.code email_skipped). An email with {{agent_output}} can only go to the automation's creator and organization admins: recipient_type team_member or team_members, with no email_addresses. This is checked when the automation is saved and again when the email sends." }, "sender": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mailbox" ] }, "nylas_grant_id": { "type": "string", "format": "uuid", "description": "A connected mailbox the automation's creator owns or has shared access to." } }, "required": [ "kind", "nylas_grant_id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "job_owner" ], "description": "Send from the job owner's mailbox. The automation's creator must have access to it when the email is sent." } }, "required": [ "kind" ] } ], "description": "Which mailbox sends the email. Required when recipient_type is candidate or client_contacts. Emails to team members come from Stardex instead." }, "team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Teammates who receive the email when recipient_type is team_members. Get IDs from GET /v1/team-members." }, "email_addresses": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "Other addresses that receive the email when recipient_type is team_members, for example finance@yourfirm.com. They get it from Stardex, like teammates do." }, "include_signature": { "type": "boolean", "description": "Add the sending mailbox's signature to the end of the email. Only applies to candidate and client_contacts emails, which are sent from a mailbox. Defaults to false." } }, "required": [ "subject", "body" ] }, { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Note text added to the candidate. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, and {{client_name}}." } }, "required": [ "content" ] }, { "type": "object", "properties": { "instructions": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Plain-English instructions for the agent, ideally with an example of the output. On a schedule trigger the agent follows them as the automation's creator, and a later email step can include its output as {{agent_output}}. On other triggers, or when the automation has no creator because it was created with an API key, the step is skipped when the automation runs (result.code agent_skipped). Agent steps are in early access; where they are not turned on, the step is saved and skipped (result.code not_implemented) and {{agent_output}} is rejected." }, "allow_update_records": { "type": "boolean", "description": "Let the agent create and update records, for example move candidates to another stage, update deals or add tasks and notes. Defaults to false, which keeps the agent read-only. Even when on, the agent cannot send email, enroll people in campaigns or sequences, run paid contact enrichment, change automations or team capacity settings, add, change or delete references, set preferred email addresses or phone numbers, mark email addresses as bounced or remove them, or change retainer packs, their retainer splits or referral partners, and it makes at most 2,000 changes in one batch." }, "allow_delete_records": { "type": "boolean", "description": "Let the agent delete, archive or remove records, for example archive a deal or remove people from a list. Defaults to false." }, "output_format": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "short_summary", "bullet_list", "table" ], "description": "short_summary: a few lines; bullet_list: one bullet per item; table: one row per item." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "custom" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 300, "description": "How the output should look, in your own words, for example \"One line per company, newest first\"." } }, "required": [ "kind", "text" ] }, { "type": "null" } ], "description": "How the agent formats its output. When set, it wins over any layout the instructions describe, except when there is nothing to list. Leave it out or set null to let the agent decide from the instructions." } }, "required": [ "instructions" ] }, { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "How many units to wait before the next action. Whole number, at least 1.", "example": 2 }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "description": "Unit for amount. A day is a fixed 24 hours.", "example": "days" } }, "required": [ "amount", "unit" ] }, { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Task text. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}} and {{client_name}} where the trigger provides them." }, "task_type": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ], "description": "Task type, the same values as tasks elsewhere in Stardex." }, "due_in_days": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 7 ] } ], "description": "Days after the step runs that the task is due. 0 means the same day.", "example": 1 } }, "required": [ "content", "task_type", "due_in_days" ] } ] } }, "required": [ "action_id", "position", "action_type", "recipient_type", "team_member_id", "payload" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "waiting", "completed", "failed", "skipped" ], "description": "Outcome of this action. `waiting` means a delay action is paused, or an agent action is still working, until `result.resume_at`. `skipped` means the action did not do anything; `result.code` says why, for example `not_implemented` for an agent action where agent steps are not turned on." }, "attempt": { "type": "integer" }, "error_message": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "What the step did: email_sent, email_skipped, sender_unavailable, note_created, task_created, waiting, delay_elapsed, agent_running, agent_completed, agent_skipped or not_implemented. A failed agent step has no code; see error_message." }, "message": { "type": "string" }, "resume_at": { "type": "string", "description": "Delay and agent actions: ISO 8601 time the step continues. For a delay, when the wait ends; while an agent works, about a minute ahead, when the step next checks whether the agent has finished." }, "from_email": { "type": "string", "description": "Send email actions only: the mailbox an external email was sent from." }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "to_email": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "skipped", "failed" ], "description": "sent, skipped (a check stopped it, see reason), or failed (the send errored for this recipient; the others were still sent)." }, "reason": { "type": "string", "description": "Why the email to this recipient was not sent." } }, "required": [ "to_email", "status" ] }, "description": "Send email actions only: the outcome for each recipient." }, "due_at": { "type": "string", "description": "Create task actions only: ISO 8601 due date of the created task." }, "sender_retry_count": { "type": "integer", "description": "Send email actions only: how many times the step waited for a sending mailbox that could not send." }, "agent_output": { "type": "string", "description": "Agent actions only: the agent's output in markdown, with links to Stardex pages relative to the app (for example /people/{id}). Longer output is cut at 20,000 characters with a note." }, "agent_thread_id": { "type": "string", "format": "uuid", "description": "Agent actions only: the Ask Dex chat the agent worked in, listed in the creator's Ask Dex chats." }, "agent_changes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "person", "candidate", "job", "company", "deal", "task", "client_contact", "list" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "name", "value" ] }, "default": [] }, "status": { "type": "string", "enum": [ "succeeded" ] } }, "required": [ "tool", "record", "status" ] }, { "type": "object", "properties": { "tool": { "type": "string" }, "record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "person", "candidate", "job", "company", "deal", "task", "client_contact", "list" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "name", "value" ] }, "default": [] }, "status": { "type": "string", "enum": [ "failed" ] }, "reason": { "type": "string" } }, "required": [ "tool", "record", "status", "reason" ] } ] }, "description": "Agent actions only: every change the agent tried, including failed ones, up to the first 500; agent_change_totals has the exact counts. A change refused because the automation was turned off or its creator left the team is not listed, since it was never made. Kept when the step fails. Each change has tool (the kind of change, for example update-candidate-stage), record (the type and id of the record a teammate would open, or null), fields (what the change set, as { name, value } pairs such as stage_id or custom_fields.Source: up to 12, text cut at 200 characters, ids left as ids; empty for runs before fields were recorded), status (succeeded or failed) and, for a failed change, reason." }, "agent_change_totals": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "tool", "succeeded", "failed" ] }, "description": "Agent actions only: for each kind of change (tool), how many went through (succeeded) and how many failed, counted exactly." } } }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "position", "action_id", "action_type", "action_config", "status", "attempt", "error_message", "result", "started_at", "finished_at", "created_at", "updated_at" ] }, "AutomationRunByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AutomationRun" } }, "required": [ "success", "data" ] }, "CalendarMeetingsListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarMeetingListItem" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CalendarMeetingListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Calendar meeting UUID." }, "meeting_title": { "type": [ "string", "null" ], "description": "Meeting title." }, "meeting_url": { "type": "string", "description": "Meeting URL." }, "start_time": { "type": "string", "description": "Meeting start time (ISO 8601)." }, "bot_status": { "type": [ "string", "null" ], "enum": [ "pending", "scheduled", "joining", "waiting_room", "in_call", "recording", "completed", "failed", "cancelled" ], "description": "Current notetaker bot status: pending, scheduled, joining, waiting_room, in_call, recording, completed, failed, or cancelled." }, "bot_opt_out": { "type": "boolean", "description": "Whether the notetaker was opted out." }, "has_recording": { "type": "boolean", "description": "Whether at least one recording exists." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "meeting_title", "meeting_url", "start_time", "bot_status", "bot_opt_out", "has_recording", "created_at", "updated_at" ] }, "CalendarMeetingByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CalendarMeetingDetail" } }, "required": [ "success", "data" ] }, "CalendarMeetingDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Calendar meeting UUID." }, "meeting_title": { "type": [ "string", "null" ], "description": "Meeting title." }, "meeting_url": { "type": "string", "description": "Meeting URL (e.g. Zoom/Google Meet link)." }, "meeting_key": { "type": "string", "description": "Unique meeting key." }, "start_time": { "type": "string", "description": "Meeting start time (ISO 8601)." }, "bot_status": { "type": [ "string", "null" ], "enum": [ "pending", "scheduled", "joining", "waiting_room", "in_call", "recording", "completed", "failed", "cancelled" ], "description": "Current notetaker bot status: pending, scheduled, joining, waiting_room, in_call, recording, completed, failed, or cancelled." }, "bot_opt_out": { "type": "boolean", "description": "Whether the notetaker bot was opted out for this meeting." }, "recordings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Meeting recording UUID. Use GET /v1/meeting-recordings/{id} for full details." }, "processing_status": { "type": [ "string", "null" ], "description": "Recording processing status: pending, processing, completed, or failed." }, "recording_duration_seconds": { "type": [ "number", "null" ], "description": "Duration of the recording in seconds." }, "has_transcript": { "type": "boolean", "description": "Whether a transcript is available. Use GET /v1/meeting-recordings/{id} to fetch the full transcript." } }, "required": [ "id", "processing_status", "recording_duration_seconds", "has_transcript" ] }, "description": "Recordings associated with this meeting." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "meeting_title", "meeting_url", "meeting_key", "start_time", "bot_status", "bot_opt_out", "recordings", "created_at", "updated_at" ] }, "CampaignsSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "keywords": { "type": "string", "maxLength": 200, "description": "Case-insensitive match on the campaign name." }, "sequence_type": { "type": "string", "enum": [ "candidate", "business_development", "candidate_nurture", "client_nurture" ], "description": "Only campaigns of this type." }, "is_archived": { "type": "boolean", "default": false, "description": "Archived campaigns only when true. Defaults to false." }, "created_by": { "type": "string", "format": "uuid", "description": "Only campaigns owned by this team member." }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at", "name", "enrollments", "reply_rate" ], "default": "created_at", "description": "Defaults to created_at. enrollments sorts by how many people were ever enrolled, reply_rate by the campaign card reply rate (campaigns with no rate last), to find the biggest or best campaigns." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Defaults to desc." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "stats" ] }, "description": "Pass [\"stats\"] to add enrollment_counts and engagement (reply, open and click rates) to each campaign." } } }, "CampaignsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSearchResult" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CampaignSearchResult": { "allOf": [ { "$ref": "#/components/schemas/CampaignSummary" }, { "type": "object", "properties": { "enrollment_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "running": { "type": "integer" }, "awaiting_task": { "type": "integer", "description": "People held until a task step is marked complete. They are also counted in running or bounced, so the groups can add up to more than total." }, "replied": { "type": "integer" }, "meeting_booked": { "type": "integer" }, "bounced": { "type": "integer" }, "completed": { "type": "integer" }, "stopped": { "type": "integer" } }, "required": [ "total", "running", "awaiting_task", "replied", "meeting_booked", "bounced", "completed", "stopped" ], "description": "People in this campaign by status. Only with include: [\"stats\"]." }, "engagement": { "type": "object", "properties": { "responded": { "type": "integer", "description": "People who replied or booked a meeting." }, "interested": { "type": "integer", "description": "People whose reply was read as interested, not counting bounced people." }, "neutral": { "type": "integer", "description": "People whose reply was read as neutral, not counting bounced people." }, "not_interested": { "type": "integer", "description": "People whose reply was read as not interested, not counting bounced people." }, "opened": { "type": "integer", "description": "People who opened at least one email, not counting bounced people." }, "clicked": { "type": "integer", "description": "People who clicked at least one link, not counting bounced people." }, "reply_rate": { "type": [ "number", "null" ], "description": "responded out of everyone enrolled except bounced people, as a percent with one decimal. null when nobody is enrolled or everyone bounced." }, "open_rate": { "type": [ "integer", "null" ], "description": "opened out of everyone enrolled except bounced people, as a whole percent. null when open tracking is off, nobody is enrolled or everyone bounced." }, "click_rate": { "type": [ "integer", "null" ], "description": "clicked out of everyone enrolled except bounced people, as a whole percent. null when link tracking is off, nobody is enrolled or everyone bounced." } }, "required": [ "responded", "interested", "neutral", "not_interested", "opened", "clicked", "reply_rate", "open_rate", "click_rate" ], "description": "Replies, opens and clicks, as on the campaign card. Only with include: [\"stats\"]." } } } ] }, "CampaignSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sequence_type": { "type": "string", "enum": [ "candidate", "business_development", "candidate_nurture", "client_nurture" ] }, "is_archived": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid", "description": "Team member who owns the campaign." }, "step_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "sequence_type", "is_archived", "created_by", "step_count", "created_at", "updated_at" ] }, "CampaignTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "candidate", "business_development", "candidate_nurture", "client_nurture" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } } }, "required": [ "success", "data" ] }, "CampaignVariablesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Use it as {{name}}." }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "sender", "job", "manual" ], "description": "person and sender are filled automatically, job comes from the job chosen at enrollment, manual is typed in." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Other spellings that also work." }, "example": { "type": "string" }, "hint": { "type": [ "string", "null" ] } }, "required": [ "name", "label", "kind", "aliases", "example", "hint" ] } } }, "required": [ "success", "data" ] }, "CampaignMailboxesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "owner_name": { "type": [ "string", "null" ] }, "is_shared": { "type": "boolean", "description": "Shared with this team member by a teammate." }, "status": { "type": "string", "enum": [ "ready", "disconnected", "rate_limited", "daily_limit_reached", "sending_disabled" ] }, "daily_limit": { "type": "integer", "description": "Campaign emails it can send per day." }, "sent_today": { "type": "integer" }, "sending_timezone": { "type": "string", "description": "Timezone the daily limit and sent_today count days in." }, "available_at": { "type": [ "string", "null" ], "description": "When it can send again, if it is paused by the daily limit or rate limiting." } }, "required": [ "email", "owner_name", "is_shared", "status", "daily_limit", "sent_today", "sending_timezone", "available_at" ] } } }, "required": [ "success", "data" ] }, "CampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } }, "required": [ "success", "data" ] }, "Campaign": { "allOf": [ { "$ref": "#/components/schemas/CampaignSummary" }, { "type": "object", "properties": { "enable_sequence_automation": { "type": "boolean" }, "stop_on_response": { "type": "boolean" }, "send_on_weekends": { "type": "boolean" }, "send_on_holidays": { "type": "boolean" }, "link_tracking": { "type": "boolean" }, "open_tracking": { "type": "boolean" }, "include_unsubscribe_link": { "type": "boolean" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStep" } }, "manual_variables": { "type": "array", "items": { "type": "string" }, "description": "Variables you fill in for each enrollment, such as personalization_line or your own names." }, "ai_variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name used in the template, without the ai: prefix. {{ai:opening_line}} has the name opening_line." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What the AI should write for each person, for example \"One sentence on their most relevant recent work\". The value is inserted exactly as written, so use the variable only where that text fits: a sentence on its own, never mid-sentence." }, "step_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Steps that use this AI variable." } }, "required": [ "name", "description", "step_ids" ] }, "description": "Variables the AI writes for each person." }, "enrollment_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "running": { "type": "integer" }, "awaiting_task": { "type": "integer", "description": "People held until a task step is marked complete. They are also counted in running or bounced, so the groups can add up to more than total." }, "replied": { "type": "integer" }, "meeting_booked": { "type": "integer" }, "bounced": { "type": "integer" }, "completed": { "type": "integer" }, "stopped": { "type": "integer" } }, "required": [ "total", "running", "awaiting_task", "replied", "meeting_booked", "bounced", "completed", "stopped" ], "description": "People in this campaign by status." }, "engagement": { "type": "object", "properties": { "responded": { "type": "integer", "description": "People who replied or booked a meeting." }, "interested": { "type": "integer", "description": "People whose reply was read as interested, not counting bounced people." }, "neutral": { "type": "integer", "description": "People whose reply was read as neutral, not counting bounced people." }, "not_interested": { "type": "integer", "description": "People whose reply was read as not interested, not counting bounced people." }, "opened": { "type": "integer", "description": "People who opened at least one email, not counting bounced people." }, "clicked": { "type": "integer", "description": "People who clicked at least one link, not counting bounced people." }, "reply_rate": { "type": [ "number", "null" ], "description": "responded out of everyone enrolled except bounced people, as a percent with one decimal. null when nobody is enrolled or everyone bounced." }, "open_rate": { "type": [ "integer", "null" ], "description": "opened out of everyone enrolled except bounced people, as a whole percent. null when open tracking is off, nobody is enrolled or everyone bounced." }, "click_rate": { "type": [ "integer", "null" ], "description": "clicked out of everyone enrolled except bounced people, as a whole percent. null when link tracking is off, nobody is enrolled or everyone bounced." } }, "required": [ "responded", "interested", "neutral", "not_interested", "opened", "clicked", "reply_rate", "open_rate", "click_rate" ], "description": "Replies, opens and clicks, as on the campaign card." } }, "required": [ "enable_sequence_automation", "stop_on_response", "send_on_weekends", "send_on_holidays", "link_tracking", "open_tracking", "include_unsubscribe_link", "steps", "manual_variables", "ai_variables", "enrollment_counts", "engagement" ] } ] }, "CampaignStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "order": { "type": "integer", "description": "1-based position in the campaign." }, "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ] }, "send_after_days": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "body_html": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "time_window_start": { "type": [ "string", "null" ], "description": "HH:MM. null means the default sending hours, 09:00–17:00 in the step's timezone." }, "time_window_end": { "type": [ "string", "null" ], "description": "HH:MM. null means the default sending hours, 09:00–17:00 in the step's timezone." }, "include_signature": { "type": "boolean" }, "block_until_task_complete": { "type": "boolean" }, "ai_variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name used in the template, without the ai: prefix. {{ai:opening_line}} has the name opening_line." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What the AI should write for each person, for example \"One sentence on their most relevant recent work\". The value is inserted exactly as written, so use the variable only where that text fits: a sentence on its own, never mid-sentence." } }, "required": [ "name", "description" ] } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string" }, "content_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer" } }, "required": [ "file_name", "content_type", "size_bytes" ] }, "description": "Files sent with this step, added in the campaign builder. Attachments cannot be added through the API." }, "created_at": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "order", "type", "send_after_days", "subject", "body_html", "timezone", "time_window_start", "time_window_end", "include_signature", "block_until_task_complete", "ai_variables", "attachments", "created_at", "updated_at" ] }, "CampaignUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Campaign name." }, "sequence_type": { "type": "string", "enum": [ "candidate", "business_development", "candidate_nurture", "client_nurture" ], "description": "Who the campaign is for. Admins only for signed-in users." }, "enable_sequence_automation": { "type": "boolean", "description": "Move people through the linked job pipeline as they reply. Admins only for signed-in users." }, "stop_on_response": { "type": "boolean", "description": "Stop emailing a person once they reply. Always off for nurture campaigns." }, "send_on_weekends": { "type": "boolean", "description": "Allow emails to go out on Saturdays and Sundays." }, "send_on_holidays": { "type": "boolean", "description": "Allow emails to go out on public holidays. When off, the campaign skips the holidays in your workspace's holiday calendar." }, "link_tracking": { "type": "boolean", "description": "Track link clicks." }, "open_tracking": { "type": "boolean", "description": "Track email opens." }, "include_unsubscribe_link": { "type": "boolean", "description": "Add an unsubscribe link to every email." }, "is_archived": { "type": "boolean", "description": "Archive or unarchive. Archiving stops everyone still in the campaign; unarchiving does not restart them." } } }, "CampaignUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "stopped_enrollment_count": { "type": "integer", "description": "People stopped because this request archived the campaign. 0 otherwise." } }, "required": [ "campaign", "stopped_enrollment_count" ] } }, "required": [ "success", "data" ] }, "CampaignCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Campaign name." }, "sequence_type": { "type": "string", "enum": [ "candidate", "business_development", "candidate_nurture", "client_nurture" ], "default": "candidate", "description": "Who the campaign is for. See GET /v1/campaigns/types. Defaults to candidate." }, "enable_sequence_automation": { "type": "boolean", "description": "Move people through the linked job pipeline as they reply. Always off for nurture campaigns." }, "stop_on_response": { "type": "boolean", "description": "Stop emailing a person once they reply. Always off for nurture campaigns." }, "send_on_weekends": { "type": "boolean", "default": false, "description": "Allow emails to go out on Saturdays and Sundays." }, "send_on_holidays": { "type": "boolean", "default": false, "description": "Allow emails to go out on public holidays. When off, the campaign skips the holidays in your workspace's holiday calendar." }, "link_tracking": { "type": "boolean", "default": true, "description": "Track link clicks." }, "open_tracking": { "type": "boolean", "default": false, "description": "Track email opens." }, "include_unsubscribe_link": { "type": "boolean", "default": false, "description": "Add an unsubscribe link to every email." }, "owner_team_member_id": { "type": "string", "format": "uuid", "description": "API keys only: the team member who owns the campaign. Defaults to the admin who created the key. Signed-in users always own the campaigns they create." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStepInput" }, "minItems": 1, "maxItems": 20, "description": "Steps in the order they run, up to 20." } }, "required": [ "name", "steps" ] }, "CampaignStepInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ], "description": "Step type. Email steps are sent automatically; the others create tasks." }, "send_after_days": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Days to wait after the previous step (or after enrollment, for the first step)." }, "subject": { "type": [ "string", "null" ], "maxLength": 998, "description": "Email subject, or the InMail subject for LinkedIn message steps. Only the first email step has its own subject: later email steps always use \"Re: \" so they land in the same thread (a \"Re:\" on the first email is removed). Editing a later email's subject is rejected. Can use {{variables}}." }, "body_html": { "type": "string", "maxLength": 100000, "description": "Step body as HTML (paragraphs, headings, line breaks, bold, italic, underline, strikethrough, highlight, links, lists and images). Each

is followed by an empty line, as in the campaign builder; use
for a line break without a gap. Images need a public https URL and are shown as their own block. Can use {{variables}}, including inside link URLs. For non-email steps this is the task or message text; LinkedIn connection notes are limited to 300 characters." }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for the sending window, for example Europe/London. Defaults to the timezone of the campaign owner's first connected mailbox. Without one, the step sends in New York business hours (America/New_York)." }, "time_window_start": { "type": [ "string", "null" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Start of the sending window for email steps, in 24-hour HH:MM. Left empty, the step sends between 09:00 and 17:00 in its timezone." }, "time_window_end": { "type": [ "string", "null" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "End of the sending window for email steps, in 24-hour HH:MM. Must differ from time_window_start." }, "include_signature": { "type": "boolean", "description": "Add the sender's email signature to this email step." }, "block_until_task_complete": { "type": "boolean", "description": "For task steps (not emails): hold the rest of the campaign until this task is marked complete. Turning it off releases anyone already waiting on the step." }, "ai_variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name used in the template, without the ai: prefix. {{ai:opening_line}} has the name opening_line." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What the AI should write for each person, for example \"One sentence on their most relevant recent work\". The value is inserted exactly as written, so use the variable only where that text fits: a sentence on its own, never mid-sentence." } }, "required": [ "name", "description" ] }, "maxItems": 20, "description": "A description for every {{ai:name}} used in this step. Descriptions for names not used in the step are ignored." } }, "required": [ "type", "send_after_days" ] }, "CampaignStepResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "step": { "$ref": "#/components/schemas/CampaignStep" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable warning code." }, "message": { "type": "string", "description": "What it means for you." } }, "required": [ "code", "message" ] } } }, "required": [ "step", "warnings" ] } }, "required": [ "success", "data" ] }, "CampaignStepUpdateRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ], "description": "Change the step type. The body is kept; people already enrolled keep the type they were enrolled with." }, "send_after_days": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Days to wait after the previous step (or after enrollment, for the first step)." }, "subject": { "type": [ "string", "null" ], "maxLength": 998, "description": "Email subject, or the InMail subject for LinkedIn message steps. Only the first email step has its own subject: later email steps always use \"Re: \" so they land in the same thread (a \"Re:\" on the first email is removed). Editing a later email's subject is rejected. Can use {{variables}}." }, "body_html": { "type": "string", "maxLength": 100000, "description": "Step body as HTML (paragraphs, headings, line breaks, bold, italic, underline, strikethrough, highlight, links, lists and images). Each

is followed by an empty line, as in the campaign builder; use
for a line break without a gap. Images need a public https URL and are shown as their own block. Can use {{variables}}, including inside link URLs. For non-email steps this is the task or message text; LinkedIn connection notes are limited to 300 characters." }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for the sending window, for example Europe/London. Defaults to the timezone of the campaign owner's first connected mailbox. Without one, the step sends in New York business hours (America/New_York)." }, "time_window_start": { "type": [ "string", "null" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Start of the sending window for email steps, in 24-hour HH:MM. Left empty, the step sends between 09:00 and 17:00 in its timezone." }, "time_window_end": { "type": [ "string", "null" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "End of the sending window for email steps, in 24-hour HH:MM. Must differ from time_window_start." }, "include_signature": { "type": "boolean", "description": "Add the sender's email signature to this email step." }, "block_until_task_complete": { "type": "boolean", "description": "For task steps (not emails): hold the rest of the campaign until this task is marked complete. Turning it off releases anyone already waiting on the step." }, "ai_variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name used in the template, without the ai: prefix. {{ai:opening_line}} has the name opening_line." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What the AI should write for each person, for example \"One sentence on their most relevant recent work\". The value is inserted exactly as written, so use the variable only where that text fits: a sentence on its own, never mid-sentence." } }, "required": [ "name", "description" ] }, "maxItems": 20, "description": "A description for every {{ai:name}} used in this step. Descriptions for names not used in the step are ignored." } } }, "CampaignStepUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "step": { "$ref": "#/components/schemas/CampaignStep" }, "applies_to_existing_enrollments": { "type": "array", "items": { "type": "string" }, "description": "Changed fields that also apply to people already enrolled. Subject, body and timing changes only apply to people enrolled after this edit." } }, "required": [ "step", "applies_to_existing_enrollments" ] } }, "required": [ "success", "data" ] }, "CampaignStepsReorderRequest": { "type": "object", "properties": { "step_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Every step id of the campaign, in the new order. Each step keeps its own wait time and settings." } }, "required": [ "step_ids" ] }, "CampaignEnrollmentStatusesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "running", "awaiting_task", "replied", "meeting_booked", "bounced", "completed", "stopped" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } } }, "required": [ "success", "data" ] }, "EnrollmentBatchCreateRequest": { "type": "object", "properties": { "sender_team_member_id": { "type": "string", "format": "uuid", "description": "Team member the emails are sent as. Required with an API key; signed-in users always send as themselves." }, "from_email": { "type": "string", "format": "email", "description": "Mailbox to send from: the sender's own or one shared with them. See GET /v1/campaigns/mailboxes." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job to add everyone to, which also fills {{search_name}}, {{search_client}} and {{application_link}}." }, "job_pipeline_stage_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Pipeline stage of job_id to put everyone in. Left out, people already on the job keep their stage and new ones start in the job's first stage." }, "start_mode": { "type": "string", "enum": [ "next_window", "now", "scheduled" ], "default": "next_window", "description": "next_window (default): the first step's wait counts from now, then the email goes out in its next sending window, skipping weekends and holidays the campaign doesn't send on. now: the first email goes out right away, even outside sending hours, on a weekend or holiday, or when the first step has a wait. scheduled: the first email goes out at start_at in start_timezone, even outside sending hours or on a weekend or holiday; if the first step has a wait, it counts from start_at and the email then goes out in the next sending window. The outside_sending_window warning tells you when the first email goes out off schedule or has to wait." }, "start_at": { "type": [ "string", "null" ], "description": "When to start, only with start_mode scheduled: a local date and time such as 2026-10-19T09:00:00, read in start_timezone, 5 minutes to 90 days ahead. A batch's timing can't be changed after it is prepared; to move it, discard the batch and prepare a new one." }, "start_timezone": { "type": [ "string", "null" ], "description": "IANA timezone for start_at, for example Europe/London. Required with start_mode scheduled." }, "email_preference": { "type": "string", "enum": [ "auto", "work", "personal" ], "default": "auto", "description": "Which email to pick for people without one given. auto: work emails for business development and client nurture campaigns, personal emails otherwise. The person's preferred email always wins." }, "variable_values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 }, "description": "Values used for everyone in the batch. A person's own variable_values win." }, "blank_variables": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "description": "Variables to leave out for everyone in the batch." }, "override_reason": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000, "description": "Reason used for every person with overrides and no own reason." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentBatchRecipientInput" }, "minItems": 1, "maxItems": 1000, "description": "People to enroll, each person once. A batch holds up to your workspace's recipient limit (50 by default), and never more than 1,000." } }, "required": [ "from_email", "recipients" ] }, "EnrollmentBatchRecipientInput": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person to enroll." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email to send to. Left out, the person's best email is picked using email_preference." }, "add_email_to_person": { "type": "boolean", "description": "Save email to the person's profile when it isn't one of their emails. A batch can't send to an address without saving it, so without this an email not on the profile leaves the person needs_input (email_not_on_person)." }, "variable_values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 }, "description": "Values for {{variables}}, keyed by the name used in the template, for example {\"personalization_line\": \"Loved your PyCon talk.\"} or {\"ai:opening_line\": \"...\"} to write an AI variable yourself." }, "blank_variables": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "description": "Variables to leave out of the email. The {{token}} is removed and the spacing around it tidied." }, "overrides": { "type": "array", "items": { "type": "string", "enum": [ "company_do_not_contact", "duplicate_enrollment" ] }, "maxItems": 2, "description": "Enroll despite these blocks: company_do_not_contact (works at a company marked do not contact) or duplicate_enrollment (already in this campaign at another email, or finished it before). Needs override_reason here or on the batch. Ignored when the person has neither block. A blocked person (unsubscribed, bounced, marked do not contact, or still in this campaign at the same email) cannot be overridden, and passing overrides for them fails the whole request with OVERRIDE_NOT_ALLOWED. To re-enroll someone at the same email, stop their enrollment first." }, "override_reason": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000, "description": "Why the block is being overridden. Stored on the enrollment." } }, "required": [ "person_id" ] }, "EnrollmentBatchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EnrollmentBatch" } }, "required": [ "success", "data" ] }, "EnrollmentBatch": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "preparing", "ready", "starting", "started", "discarded", "expired" ], "description": "preparing: AI variables are being written. ready: can be edited and started. starting: people are enrolled and adding them to the job or as client contacts is still finishing. started, discarded, expired: final." }, "version": { "type": "integer", "description": "Goes up with every change. Pass it to start." }, "source": { "type": "string", "enum": [ "api", "mcp", "copilot", "app" ], "description": "Where the batch was made: api (an API key), mcp (an AI assistant connected over MCP), copilot (Ask Dex) or app (a signed-in user calling the API)." }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "sender": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "from_email": { "type": "string" } }, "required": [ "team_member_id", "name", "from_email" ] }, "job": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "pipeline_stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "pipeline_stage": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "pipeline_stage_id", "pipeline_stage" ] }, "start": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "next_window", "now", "scheduled" ] }, "at": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] } }, "required": [ "mode", "at", "timezone" ] }, "created_by": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key", "team_member" ] }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "name" ], "description": "Who prepared the batch: an API key, with its name, or a team member. Only they can change, start or discard it." }, "created_at": { "type": "string" }, "expires_at": { "type": "string", "description": "A draft expires 24 hours after its last change." }, "started_at": { "type": [ "string", "null" ] }, "progress": { "type": [ "object", "null" ], "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "done", "total" ], "description": "AI writing progress while preparing." }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "preparing": { "type": "integer" }, "ready": { "type": "integer" }, "needs_input": { "type": "integer" }, "blocked": { "type": "integer" }, "excluded": { "type": "integer" }, "enrolled": { "type": "integer" }, "rejected_at_start": { "type": "integer" } }, "required": [ "total", "preparing", "ready", "needs_input", "blocked", "excluded", "enrolled", "rejected_at_start" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "exceeds_daily_capacity, daily_limit_reached (the mailbox already sent its daily limit today and the first email is due today, so it waits for the reset), sending_disabled, mailbox_rate_limited, outside_sending_window, adds_to_job_pipeline, creates_client_contacts, contains_overrides (details has the names), shared_email (one per email several people use; details has the email and the names), job_automation_will_run or steps_without_timezone. outside_sending_window means the first email goes out outside sending hours, on a weekend or on a holiday the campaign skips (start_mode now or scheduled), or has to wait for the next sending window (next_window); details has reason (outside_hours, weekend or holiday), sending_hours and first_email_at." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": "Extra facts about the issue, such as variable names." } }, "required": [ "code", "message" ] } }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "recipient_id": { "type": "string", "format": "uuid" }, "person_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "preparing", "ready", "needs_input", "blocked", "excluded", "enrolled", "rejected_at_start" ], "description": "ready: enrolled at start. needs_input and blocked: not enrolled; see issues. excluded: left out by you. preparing: AI variables are still being written. After start: enrolled or rejected_at_start." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Blocks: person_not_found, email_bounced, unsubscribed, person_do_not_contact, already_enrolled. Needs input: no_email, email_not_on_person, company_do_not_contact, already_enrolled_different_email, previously_completed, missing_variables, ai_generation_failed. Warnings: likely_bounce, enrolled_in_other_campaign, previously_in_campaign (was in this campaign before and was stopped, cancelled or failed)." }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": "Extra facts about the issue, such as variable names." } }, "required": [ "code", "message" ] } }, "overrides": { "type": "array", "items": { "type": "string", "enum": [ "company_do_not_contact", "duplicate_enrollment" ] }, "description": "Blocks this person is enrolled despite." }, "override_reason": { "type": [ "string", "null" ] }, "enrollment_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set once enrolled." }, "first_email_estimated_at": { "type": [ "string", "null" ], "description": "Estimated time of this person's first email, following start_mode and moved to later days when the batch is more than the mailbox's daily limit can send. null when the person isn't ready, the first step isn't an email, or the mailbox's daily limit is 0." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid", "description": "Campaign step ID." }, "order": { "type": "integer", "description": "1-based position in the campaign." }, "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ] }, "send_after_days": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "body_html": { "type": "string" }, "edited": { "type": "boolean", "description": "Edited for this person, so variable changes don't rewrite it." } }, "required": [ "step_id", "order", "type", "send_after_days", "subject", "body_html", "edited" ] }, "description": "Only with include=content." } }, "required": [ "recipient_id", "person_id", "name", "email", "status", "issues", "overrides", "override_reason", "enrollment_id", "first_email_estimated_at" ] } }, "sample": { "type": [ "object", "null" ], "properties": { "recipient_id": { "type": "string", "format": "uuid" }, "subject": { "type": [ "string", "null" ] }, "body_text": { "type": "string" } }, "required": [ "recipient_id", "subject", "body_text" ], "description": "The first ready person's first email, as plain text." } }, "required": [ "batch_id", "status", "version", "source", "campaign", "sender", "job", "start", "created_by", "created_at", "expires_at", "started_at", "progress", "summary", "warnings", "recipients", "sample" ] }, "EnrollmentBatchRecipientResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EnrollmentBatchRecipient" } }, "required": [ "success", "data" ] }, "EnrollmentBatchRecipient": { "type": "object", "properties": { "recipient_id": { "type": "string", "format": "uuid" }, "person_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "preparing", "ready", "needs_input", "blocked", "excluded", "enrolled", "rejected_at_start" ], "description": "ready: enrolled at start. needs_input and blocked: not enrolled; see issues. excluded: left out by you. preparing: AI variables are still being written. After start: enrolled or rejected_at_start." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Blocks: person_not_found, email_bounced, unsubscribed, person_do_not_contact, already_enrolled. Needs input: no_email, email_not_on_person, company_do_not_contact, already_enrolled_different_email, previously_completed, missing_variables, ai_generation_failed. Warnings: likely_bounce, enrolled_in_other_campaign, previously_in_campaign (was in this campaign before and was stopped, cancelled or failed)." }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": "Extra facts about the issue, such as variable names." } }, "required": [ "code", "message" ] } }, "overrides": { "type": "array", "items": { "type": "string", "enum": [ "company_do_not_contact", "duplicate_enrollment" ] }, "description": "Blocks this person is enrolled despite." }, "override_reason": { "type": [ "string", "null" ] }, "enrollment_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set once enrolled." }, "first_email_estimated_at": { "type": [ "string", "null" ], "description": "Estimated time of this person's first email, following start_mode and moved to later days when the batch is more than the mailbox's daily limit can send. null when the person isn't ready, the first step isn't an email, or the mailbox's daily limit is 0." }, "add_email_to_person": { "type": "boolean" }, "blank_variables": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "person", "sender", "job", "provided", "provided_for_batch", "ai" ] } }, "required": [ "value", "source" ] }, "description": "Every filled variable and where its value came from." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid", "description": "Campaign step ID." }, "order": { "type": "integer", "description": "1-based position in the campaign." }, "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ] }, "send_after_days": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "body_html": { "type": "string" }, "edited": { "type": "boolean", "description": "Edited for this person, so variable changes don't rewrite it." } }, "required": [ "step_id", "order", "type", "send_after_days", "subject", "body_html", "edited" ] } } }, "required": [ "recipient_id", "person_id", "name", "email", "status", "issues", "overrides", "override_reason", "enrollment_id", "first_email_estimated_at", "add_email_to_person", "blank_variables", "variables", "steps" ] }, "EnrollmentBatchRecipientUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Send to this email instead." }, "add_email_to_person": { "type": "boolean", "description": "Save email to the person's profile when it isn't one of their emails. A batch can't send to an address without saving it, so without this an email not on the profile leaves the person needs_input (email_not_on_person)." }, "variable_values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 }, "description": "Values to set for this person, merged into the ones already given. An empty string removes a value." }, "blank_variables": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "description": "Variables to leave out for this person, dropping any value given for them. Replaces the list already given." }, "overrides": { "type": "array", "items": { "type": "string", "enum": [ "company_do_not_contact", "duplicate_enrollment" ] }, "maxItems": 2, "description": "Enroll despite these blocks: company_do_not_contact (works at a company marked do not contact) or duplicate_enrollment (already in this campaign at another email, or finished it before). Needs override_reason here or on the batch. Ignored when the person has neither block. A blocked person (unsubscribed, bounced, marked do not contact, or still in this campaign at the same email) cannot be overridden, and passing overrides for them fails the whole request with OVERRIDE_NOT_ALLOWED. To re-enroll someone at the same email, stop their enrollment first." }, "override_reason": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000, "description": "Why the block is being overridden. Stored on the enrollment." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid", "description": "Campaign step ID." }, "subject": { "type": [ "string", "null" ], "maxLength": 998, "description": "Only the first email step has its own subject. Later email steps reply in its thread as \"Re: \", so a different subject on them is rejected; changing the first subject renames them too." }, "body_html": { "type": "string", "maxLength": 100000 } }, "required": [ "step_id" ] }, "maxItems": 20, "description": "Final text for this person's steps, with no {{variables}} left. Edited steps keep this text even when variables change." }, "excluded": { "type": "boolean", "description": "Leave this person out of the batch, or put them back." } } }, "EnrollmentBatchAddRecipientsRequest": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentBatchRecipientInput" }, "minItems": 1, "maxItems": 1000, "description": "People to enroll, each person once. A batch holds up to your workspace's recipient limit (50 by default), and never more than 1,000." } }, "required": [ "recipients" ] }, "EnrollmentBatchStartRequest": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1, "description": "The batch version you read. Start fails if it has changed." }, "expected_recipient_count": { "type": "integer", "minimum": 0, "description": "How many people you expect to enroll: summary.ready from the batch you read." }, "from_email": { "type": "string", "format": "email", "description": "The mailbox you expect it to send from. When given and different from the batch, start fails with 409 SENDER_MISMATCH." } }, "required": [ "version", "expected_recipient_count" ] }, "EnrollmentBatchStartResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EnrollmentBatchStartResult" } }, "required": [ "success", "data" ] }, "EnrollmentBatchStartResult": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "starting", "started" ] }, "replayed": { "type": "boolean", "description": "True when this batch had already started and this call returned or finished that result." }, "summary": { "type": "object", "properties": { "enrolled": { "type": "integer" }, "rejected_at_start": { "type": "integer" }, "not_enrolled": { "type": "integer" } }, "required": [ "enrolled", "rejected_at_start", "not_enrolled" ] }, "enrollments": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "enrollment_id": { "type": "string", "format": "uuid" }, "first_email_estimated_at": { "type": [ "string", "null" ] } }, "required": [ "person_id", "enrollment_id", "first_email_estimated_at" ] } }, "not_enrolled": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "preparing", "ready", "needs_input", "blocked", "excluded", "enrolled", "rejected_at_start" ] } }, "required": [ "person_id", "status" ] } }, "rejected_at_start": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Blocks: person_not_found, email_bounced, unsubscribed, person_do_not_contact, already_enrolled. Needs input: no_email, email_not_on_person, company_do_not_contact, already_enrolled_different_email, previously_completed, missing_variables, ai_generation_failed. Warnings: likely_bounce, enrolled_in_other_campaign, previously_in_campaign (was in this campaign before and was stopped, cancelled or failed)." }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": "Extra facts about the issue, such as variable names." } }, "required": [ "code", "message" ] } } }, "required": [ "person_id", "issues" ] } }, "follow_up_errors": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "required": [ "person_id", "message" ] }, "description": "People who are enrolled but whose follow-up did not finish: adding them to the job (retried automatically), saving their email as preferred, or adding them as a client contact." } }, "required": [ "batch_id", "status", "replayed", "summary", "enrollments", "not_enrolled", "rejected_at_start", "follow_up_errors" ] }, "EnrollmentBatchDiscardResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "discarded" ] } }, "required": [ "batch_id", "status" ] } }, "required": [ "success", "data" ] }, "EnrollmentsSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "status": { "type": "string", "enum": [ "running", "awaiting_task", "replied", "meeting_booked", "bounced", "completed", "stopped" ], "description": "Only people in this status group. See GET /v1/campaigns/enrollment-statuses." }, "person_id": { "type": "string", "format": "uuid", "description": "Only enrollments of this person." }, "job_id": { "type": "string", "format": "uuid", "description": "Only people enrolled with this job." }, "batch_id": { "type": "string", "format": "uuid", "description": "Only people enrolled by this enrollment batch." }, "source": { "type": "string", "enum": [ "api", "mcp", "copilot", "app" ], "description": "Only people enrolled through an enrollment batch from this source: api (an API key), mcp (an AI assistant connected over MCP), copilot (Ask Dex) or app (a signed-in user calling the API). People enrolled in the Stardex app have no source and are left out." }, "enrolled_after": { "type": "string", "format": "date-time", "description": "Only people enrolled at or after this time." }, "enrolled_before": { "type": "string", "format": "date-time", "description": "Only people enrolled at or before this time." }, "current_step": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Only people currently on this step, counting from 1. Only running people have a current step." }, "reply_intent": { "type": "string", "enum": [ "positive", "neutral", "negative" ], "description": "Only people whose reply was read as positive (interested), neutral or negative (not interested)." }, "min_opens": { "type": "integer", "minimum": 0, "maximum": 32767, "description": "Only people who opened the emails at least this many times." }, "max_opens": { "type": "integer", "minimum": 0, "maximum": 32767, "description": "Only people who opened the emails at most this many times. 0 finds people who never opened, including bounced people." }, "min_clicks": { "type": "integer", "minimum": 0, "maximum": 32767, "description": "Only people who clicked links at least this many times." }, "max_clicks": { "type": "integer", "minimum": 0, "maximum": 32767, "description": "Only people who clicked links at most this many times. 0 finds people who never clicked." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Only people whose name or email contains this text." }, "sort_by": { "type": "string", "enum": [ "enrolled_at", "name", "status", "next_step_at", "opens", "clicks" ], "default": "enrolled_at", "description": "Defaults to enrolled_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Defaults to desc." } } }, "EnrollmentsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignEnrollment" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CampaignEnrollment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "person_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "Detailed status: active, pending, replied, event_scheduled, bounced, exited, stopped, cancelled, failed or access_revoked. status_group groups these." }, "status_group": { "type": [ "string", "null" ], "enum": [ "running", "awaiting_task", "replied", "meeting_booked", "bounced", "completed", "stopped" ], "description": "The status group of status. People held by a task step show as running or bounced here; search with status awaiting_task to find them." }, "from_email": { "type": [ "string", "null" ] }, "sender_team_member_id": { "type": [ "string", "null" ], "format": "uuid" }, "job_id": { "type": [ "string", "null" ], "format": "uuid" }, "enrolled_at": { "type": "string" }, "current_step": { "type": [ "integer", "null" ], "description": "1-based step the person is on, while running." }, "next_step_at": { "type": [ "string", "null" ] }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "reply_intent": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative" ], "description": "How their reply was read: positive (interested), neutral or negative (not interested). null until they reply." }, "batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": [ "string", "null" ], "enum": [ "api", "mcp", "copilot", "app" ], "description": "Where the enrollment batch that enrolled them was made: api (an API key), mcp (an AI assistant connected over MCP), copilot (Ask Dex) or app (a signed-in user calling the API). null for people enrolled in the Stardex app." } }, "required": [ "id", "person_id", "name", "email", "status", "status_group", "from_email", "sender_team_member_id", "job_id", "enrolled_at", "current_step", "next_step_at", "opens", "clicks", "reply_intent", "batch_id", "source" ] }, "CampaignEnrollmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignEnrollmentDetail" } }, "required": [ "success", "data" ] }, "CampaignEnrollmentDetail": { "allOf": [ { "$ref": "#/components/schemas/CampaignEnrollment" }, { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "step_id": { "type": "string", "format": "uuid", "description": "Campaign step it was copied from." }, "order": { "type": "integer" }, "type": { "type": "string", "enum": [ "email", "manual", "text", "linkedin_message", "linkedin_connection", "call" ] }, "subject": { "type": [ "string", "null" ] }, "body_html": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "editable": { "type": "boolean", "description": "Not sent and not being sent, so subject and body can still be changed." } }, "required": [ "id", "step_id", "order", "type", "subject", "body_html", "status", "due_at", "sent_at", "editable" ] } } }, "required": [ "steps" ] } ] }, "EnrollmentStepUpdateRequest": { "type": "object", "properties": { "subject": { "type": [ "string", "null" ], "maxLength": 998, "description": "Only the first email step has its own subject. Later email steps reply in its thread as \"Re: \", so a different subject on them is rejected; changing the first subject renames this person's later emails that are not sent yet." }, "body_html": { "type": "string", "maxLength": 100000 } } }, "EnrollmentsStopRequest": { "type": "object", "properties": { "enrollment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500, "description": "Enrollments of this campaign to stop, up to 500. Pass this or batch_id, not both." }, "batch_id": { "type": "string", "format": "uuid", "description": "Stop everyone this enrollment batch enrolled who is still running, which undoes its start. Pass this or enrollment_ids, not both." } } }, "EnrollmentStopResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "stopped_enrollment_count": { "type": "integer", "description": "People stopped by this request. People who already replied, booked a meeting, finished or were stopped are left as they are and not counted." } }, "required": [ "stopped_enrollment_count" ] } }, "required": [ "success", "data" ] }, "UpdateCandidateStageBody": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID. Highest-precedence job identifier. Get IDs from POST /v1/jobs/search." }, "job_name": { "type": "string", "minLength": 1, "description": "Job title to match. Used only when job_id and candidate_id do not resolve a job. If no job is resolved, the endpoint falls back to the person’s most recent active candidacy created within the previous 180 days." }, "candidate_id": { "type": "string", "format": "uuid", "description": "Candidate UUID. Its associated job is used after an explicit job_id and before job_name. Provide candidate_id, candidate_email, or candidate_name." }, "candidate_email": { "type": "string", "format": "email", "description": "Candidate email to look up. Used when candidate_id is not provided." }, "candidate_name": { "type": "string", "minLength": 1, "description": "Candidate full name to look up. Fallback when email and ID are not provided." }, "stage_id": { "type": "string", "minLength": 1, "description": "Target pipeline stage UUID. Provide either stage_id or stage_name. Get IDs from GET /v1/jobs/{id} → pipeline_stages. An archived stage is rejected with a 400 STAGE_ARCHIVED error." }, "stage_name": { "type": "string", "minLength": 1, "description": "Target pipeline stage name (e.g. \"Technical Interview\"). Used when stage_id is not provided. An archived stage is rejected with a 400 STAGE_ARCHIVED error." }, "rejection_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Rejection reason UUID from GET /v1/candidates/rejection-reasons. Only allowed when moving to a rejection stage. Pass null to record no predefined reason." }, "reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining the stage change. Only allowed when moving to a rejection stage. Pass null to record no note." } } }, "UpdateCandidateStageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the stage update succeeded." }, "data": { "type": "object", "properties": { "candidate_id": { "type": "string", "description": "Candidate UUID that was updated." }, "job_id": { "type": "string", "description": "Job UUID." }, "person_id": { "type": "string", "description": "Associated person UUID." }, "previous_stage_id": { "type": [ "string", "null" ], "description": "Job pipeline stage UUID the candidate was in before the move. Matches job_pipeline_stage_id in GET /v1/jobs/{id} → pipeline_stages." }, "new_stage_id": { "type": "string", "description": "Job pipeline stage UUID the candidate was moved to. Matches job_pipeline_stage_id in GET /v1/jobs/{id} → pipeline_stages." }, "pipeline_status_id": { "type": "string", "format": "uuid", "description": "Pipeline status UUID created for this move. Matches the synthetic pipeline_status activity ID in GET /v1/persons/{id}/activities." }, "reason_text": { "type": [ "string", "null" ], "description": "Recorded free-text rejection or stage-change reason." }, "rejection_reason": { "allOf": [ { "$ref": "#/components/schemas/CandidateRejectionReason" }, { "type": [ "object", "null" ], "description": "Recorded predefined rejection reason. Null when no predefined reason was recorded." } ] } } } }, "required": [ "success", "data" ] }, "CandidateRejectionReason": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Rejection reason UUID." }, "reason": { "type": "string", "description": "Rejection reason label." } }, "required": [ "id", "reason" ] }, "RejectionReasonsListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateRejectionReason" } } }, "required": [ "success", "data" ] }, "CandidateByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CandidateById" } }, "required": [ "success", "data" ] }, "CandidateById": { "type": "object", "properties": { "id": { "type": "string", "description": "Candidate UUID." }, "person_id": { "type": "string", "description": "Associated person UUID. Use in GET /v1/persons/{id} for full profile." }, "job_id": { "type": "string", "description": "Associated job UUID. Use in GET /v1/jobs/{id} for job details and pipeline stages." }, "name": { "type": [ "string", "null" ], "description": "Candidate full name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title from their person profile." }, "current_company_name": { "type": [ "string", "null" ], "description": "Current employer name." }, "current_company_id": { "type": [ "string", "null" ], "description": "Current employer company UUID." }, "current_pipeline_stage_name": { "type": [ "string", "null" ], "description": "Name of the current pipeline stage." }, "current_pipeline_stage_id": { "type": [ "string", "null" ], "description": "UUID of the current pipeline stage. Stage IDs from GET /v1/jobs/{id} → pipeline_stages." }, "current_pipeline_stage_date": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the candidate entered the current stage." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the person was added as a candidate to this job." }, "sourced_by": { "type": [ "string", "null" ], "description": "UUID of the team member who sourced this candidate. Matches IDs from GET /v1/team-members." }, "owner_id": { "type": [ "string", "null" ], "description": "UUID of the team member who owns this candidate. Matches IDs from GET /v1/team-members." }, "pipeline_stage_history": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStageHistoryItem" }, "description": "Complete history of all pipeline stages this candidate has been through, ordered chronologically." } }, "required": [ "id", "person_id", "job_id", "name", "current_job_title", "current_company_name", "current_company_id", "current_pipeline_stage_name", "current_pipeline_stage_id", "current_pipeline_stage_date", "created_at", "sourced_by", "owner_id", "pipeline_stage_history" ] }, "PipelineStageHistoryItem": { "type": "object", "properties": { "pipeline_status_id": { "type": "string", "format": "uuid", "description": "Pipeline status UUID. Matches the synthetic pipeline_status activity ID in GET /v1/persons/{id}/activities." }, "stage_id": { "type": "string", "description": "Pipeline stage UUID." }, "stage_name": { "type": "string", "description": "Stage display name." }, "stage_date": { "type": "string", "description": "ISO 8601 timestamp when the candidate entered this stage." }, "reason_text": { "type": [ "string", "null" ], "description": "Free-text rejection or stage-change reason." }, "rejection_reason": { "allOf": [ { "$ref": "#/components/schemas/CandidateRejectionReason" }, { "type": [ "object", "null" ], "description": "Selected rejection reason. Null when no predefined rejection reason was recorded." } ] } }, "required": [ "pipeline_status_id", "stage_id", "stage_name", "stage_date", "reason_text", "rejection_reason" ] }, "ClientContactStatusesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientContactStatusItem" } } }, "required": [ "success", "data" ] }, "ClientContactStatusItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client contact status UUID." }, "name": { "type": "string", "description": "Status label for client contacts (e.g. \"Active\", \"Churned\")." }, "color": { "type": [ "string", "null" ], "description": "Hex color code." }, "stage_order": { "type": [ "number", "null" ], "description": "Display order within the contact status pipeline." }, "is_default_status": { "type": "boolean", "description": "Whether this is the default status for new client contacts." } }, "required": [ "id", "name", "color", "stage_order", "is_default_status" ] }, "ClientContactsListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientContact" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "ClientContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client contact UUID." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Person UUID linked to this client contact." }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client company UUID this contact belongs to." }, "client_contact_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assigned client contact status UUID, if any." }, "person": { "allOf": [ { "$ref": "#/components/schemas/ClientContactPerson" }, { "type": [ "object", "null" ], "description": "Linked person summary. Null when the person record is missing." } ] }, "company": { "allOf": [ { "$ref": "#/components/schemas/ClientContactCompany" }, { "type": [ "object", "null" ], "description": "Linked client company summary. Null when no company is linked." } ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/ClientContactStatusItem" }, { "type": [ "object", "null" ], "description": "Assigned status details. Null when the contact has no status." } ] }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs assigned as owners." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." }, "is_referral_partner": { "type": "boolean", "description": "True when this contact is a referral partner on at least one job. Manage partners with /v1/jobs/{id}/referral-partners." }, "referred_jobs": { "type": "array", "items": { "$ref": "#/components/schemas/ClientContactReferredJob" }, "description": "Jobs this contact referred, oldest referral first. Lists only jobs you can see, so it can be empty while is_referral_partner is true." } }, "required": [ "id", "person_id", "client_id", "client_contact_status_id", "person", "company", "status", "owner_ids", "created_at", "updated_at", "is_referral_partner", "referred_jobs" ] }, "ClientContactPerson": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Person UUID." }, "name": { "type": [ "string", "null" ], "description": "Full name." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title." }, "image_url": { "type": [ "string", "null" ], "description": "Profile image URL." }, "date_of_last_engagement": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent activity or communication with this person." } }, "required": [ "id", "name", "first_name", "last_name", "current_job_title", "image_url", "date_of_last_engagement" ] }, "ClientContactCompany": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client company UUID. Same as `client_id`." }, "name": { "type": "string", "description": "Company display name." }, "domain": { "type": [ "string", "null" ], "description": "Company domain, if known." } }, "required": [ "id", "name", "domain" ] }, "ClientContactReferredJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID. Use GET /v1/jobs/{id} for details." }, "job_title": { "type": "string", "description": "Job title." } }, "required": [ "job_id", "job_title" ] }, "CreateClientContactRequest": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID to promote into a client contact. Get IDs from POST /v1/persons/search or POST /v1/persons." }, "client_id": { "type": "string", "format": "uuid", "description": "Client company UUID this person belongs to. Get IDs from GET /v1/companies. The company is automatically flagged as a client when this contact is created." }, "client_contact_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional client contact status UUID. When omitted, the team default status is used. Use GET /v1/client-contacts/statuses to discover available status IDs." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional team member UUIDs to assign as client-contact owners. If omitted, the authenticated caller (when they are a team member) is auto-assigned. Pass an empty array to create the contact with no owners." } }, "required": [ "person_id", "client_id" ] }, "CreateClientContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created client contact UUID." }, "person_id": { "type": "string", "format": "uuid", "description": "Person UUID linked to this client contact." }, "client_id": { "type": "string", "format": "uuid", "description": "Client company UUID this contact belongs to." }, "client_contact_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assigned client contact status UUID, if any." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs assigned as owners." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "is_new": { "type": "boolean", "description": "True when a new client contact row was created. False when an existing client contact for this person was returned instead — in that case the echoed `client_id` may differ from the requested value if the person was already linked to a different client company." } }, "required": [ "id", "person_id", "client_id", "client_contact_status_id", "owner_ids", "created_at", "is_new" ] } }, "required": [ "success", "data" ] }, "ClientContactByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ClientContact" } }, "required": [ "success", "data" ] }, "UpdateClientContactRequest": { "type": "object", "properties": { "client_contact_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client contact status UUID, or null to clear the status. Omit to leave the status unchanged. Use GET /v1/client-contacts/statuses to get available status IDs." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to set as the client contact owners. Replaces all current owners. Pass an empty array to remove all owners. Omit to leave owners unchanged. Get IDs from GET /v1/team-members." } } }, "UpdateClientContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client contact UUID." }, "client_contact_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client contact status UUID after the update." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs assigned as owners after the update." }, "message": { "type": "string", "description": "Confirmation message." } }, "required": [ "id", "client_contact_status_id", "owner_ids", "message" ] } }, "required": [ "success", "data" ] }, "CompanyClientStatusesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyClientStatusItem" } } }, "required": [ "success", "data" ] }, "CompanyClientStatusItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client status UUID." }, "name": { "type": "string", "description": "Status label (e.g. \"Active Client\", \"Prospect\", \"Former Client\")." }, "color": { "type": [ "string", "null" ], "description": "Hex color code." }, "stage_order": { "type": [ "number", "null" ], "description": "Display order within the client pipeline." }, "is_default_status": { "type": "boolean", "description": "Whether this is the default status for new clients." } }, "required": [ "id", "name", "color", "stage_order", "is_default_status" ] }, "CompaniesSearchBody": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records to return (1–100). Defaults to 100." }, "sort_by": { "type": "string", "description": "Column to sort by. Accepted values:\n- `name` — company name (alphabetical)\n- `domain` — website domain (alphabetical)\n- `status` — client status (by stage order)\n- `date_of_last_engagement` — most recent engagement date\n- `created_at` — creation timestamp (default)\n- `custom_` — any custom attribute UUID prefixed with `custom_` (e.g. `custom_e5f6a7b8-c9d0-1234-efab-567890123456`). Sorts by the attribute's decimal, date, string, or tag value." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Full-text search across company name, domain, and LinkedIn URL." }, "domain": { "type": "string", "description": "Filter by exact website domain (e.g. \"acme.com\")." }, "linkedin_url": { "type": "string", "description": "Filter by exact LinkedIn company URL." }, "is_client": { "type": "boolean", "description": "Filter by client status. true = clients only, false = non-clients, omit = all." }, "job_id": { "type": "string", "format": "uuid", "description": "Filter to target companies of this job." }, "list_id": { "type": "string", "format": "uuid", "description": "Filter to companies belonging to this list." }, "company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Pre-filter to a specific set of company IDs." }, "company_status_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only companies with these client status IDs." }, "company_status_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude companies with these client status IDs." }, "owner_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only companies owned by these team members. Get IDs from GET /v1/team-members." }, "owner_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude companies owned by these team members." }, "relationships_included": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "UUID of the related company." }, "relationship_type": { "type": "string", "description": "Relationship type key. Omit to match any relationship with this company." } }, "required": [ "company_id" ] }, "description": "Include only companies with a relationship to any of these companies." }, "relationships_excluded": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "UUID of the related company." }, "relationship_type": { "type": "string", "description": "Relationship type key. Omit to match any relationship with this company." } }, "required": [ "company_id" ] }, "description": "Exclude companies with a relationship to these companies." }, "list_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include companies belonging to any of these lists." }, "list_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude companies belonging to any of these lists." }, "job_association": { "type": "string", "enum": [ "has_jobs", "no_jobs" ], "description": "Filter by job association. \"has_jobs\" returns companies with at least one non-deleted job. \"no_jobs\" returns companies with no jobs." }, "job_status_filter": { "type": "string", "enum": [ "active_or_archived", "active_only", "archived_only" ], "description": "When job_association is \"has_jobs\", further filter by job status. \"active_or_archived\" (default) matches any non-deleted job. \"active_only\" matches companies with at least one active (non-archived) job. \"archived_only\" matches companies that only have archived jobs (no active ones)." }, "select_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions." }, "excluded_values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/companies." }, "numeric_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}." }, "min": { "type": [ "number", "null" ], "description": "Minimum value (inclusive). Null for no lower bound." }, "max": { "type": [ "number", "null" ], "description": "Maximum value (inclusive). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/companies." }, "date_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}." }, "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/companies." }, "team_member_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to include. Get IDs from GET /v1/team-members." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified team members (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no team member assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/companies." }, "company_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-company type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to include. Get IDs from GET /v1/companies/search or search-companies." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified companies (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no company assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by multi-company custom fields. Get attribute_id from GET /v1/custom-fields/companies." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields" ] }, "description": "Extra sections to embed. Values: custom_fields. Omit for base fields only." } } }, "CompaniesSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchItem" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CompanySearchItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Company UUID." }, "name": { "type": "string", "description": "Company name." }, "domain": { "type": [ "string", "null" ], "description": "Website domain." }, "linkedin_url": { "type": [ "string", "null" ], "description": "LinkedIn company page URL." }, "location": { "type": [ "string", "null" ], "description": "Company headquarters location." }, "is_client": { "type": "boolean", "description": "True if company is a client." }, "do_not_contact": { "type": "boolean", "description": "True if flagged do-not-contact." }, "do_not_contact_metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Do-not-contact metadata (reason, set_by, etc.)." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent update." }, "updated_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who last updated this company. Null if the last update came from a system/automated process." }, "client_status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Client status UUID." }, "name": { "type": "string", "description": "Client status label (e.g. \"Active\", \"Prospect\", \"Former Client\")." } }, "required": [ "id", "name" ], "description": "Client lifecycle status with id and name. Null if no status assigned." }, "date_of_last_engagement": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent engagement." }, "enriched_company": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Enriched company UUID." }, "name": { "type": "string", "description": "Enriched company name." }, "domain": { "type": [ "string", "null" ], "description": "Enriched domain." }, "linkedin_url": { "type": [ "string", "null" ], "description": "Enriched LinkedIn URL." } }, "required": [ "id", "name", "domain", "linkedin_url" ], "description": "Enriched company data snapshot." }, "job_target_companies": { "type": "array", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job UUID." }, "organization_company_id": { "type": "string", "description": "Company UUID." }, "notes": { "type": [ "string", "null" ], "description": "Target company notes." } }, "required": [ "job_id", "organization_company_id", "notes" ] }, "description": "Job target company associations (populated when job_id filter is used)." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ] }, "description": "Team members who own this company." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "relation_type": { "type": "string", "description": "Relationship type key." }, "relation_type_name": { "type": "string", "description": "Relationship type display name." }, "related_company_id": { "type": "string", "description": "Related company UUID." }, "related_company_name": { "type": "string", "description": "Related company name." }, "note": { "type": [ "string", "null" ], "description": "Optional note." } }, "required": [ "relation_type", "relation_type_name", "related_company_id", "related_company_name", "note" ] }, "description": "Company relationships (populated when relationship filter is active)." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom field values. Included when include contains \"custom_fields\"." } }, "required": [ "id", "name", "domain", "linkedin_url", "location", "is_client", "do_not_contact", "do_not_contact_metadata", "created_at", "updated_at", "updated_by", "client_status", "date_of_last_engagement", "enriched_company", "job_target_companies", "owners", "relationships" ] }, "CustomFieldValue": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get definitions from GET /v1/custom-fields/{entity}." }, "attribute_name": { "type": "string", "description": "Attribute display name." }, "data_type": { "type": "string", "enum": [ "string", "integer", "decimal", "multi-select", "single-select", "boolean", "date", "multi-team-member", "multi-company", "url" ], "description": "Attribute data type. Determines which value field contains the data." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this attribute is scoped to. Null for global person-level attributes. Present when this custom field is specific to a job (candidate-level field)." }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "description": "List UUID this attribute is scoped to. Null for global person-level attributes." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "Scalar value for string, integer, decimal, date, url, boolean types. Null for select/team-member/company types." }, "tag": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag option UUID." }, "name": { "type": "string", "description": "Tag display name." } }, "required": [ "id", "name" ], "description": "Tag value for single-select and multi-select types. Null for other types. For multi-select, one CustomFieldValue row per tag." }, "team_member": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "name": { "type": [ "string", "null" ], "description": "Team member full name." } }, "required": [ "id", "name" ], "description": "Team member value for multi-team-member type. Null for other types. One CustomFieldValue row per team member." }, "company": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Company UUID." }, "name": { "type": [ "string", "null" ], "description": "Company display name." } }, "required": [ "id", "name" ], "description": "Company value for multi-company type. Null for other types. One CustomFieldValue row per company." } }, "required": [ "attribute_id", "attribute_name", "data_type", "job_id", "list_id", "value", "tag", "team_member", "company" ] }, "CompanyCreateOrUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name." }, "domain": { "type": "string", "description": "Website domain." }, "linkedin_url": { "type": "string", "description": "LinkedIn company page URL." }, "description": { "type": "string", "description": "Company description." }, "location": { "type": "string", "description": "Company headquarters location." }, "phone": { "type": "string", "description": "Company phone number." }, "is_client": { "type": "boolean", "description": "Whether to mark the company as a client." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/companies." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/companies." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all existing values for this multi-select, multi-team-member, or multi-company attribute." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to set. Get attribute definitions from GET /v1/custom-fields/companies." } } }, "CompanyCreateOrUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CompanyDetail" } }, "required": [ "success", "data" ] }, "CompanyDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Company UUID." }, "name": { "type": "string", "description": "Company name." }, "domain": { "type": [ "string", "null" ], "description": "Website domain." }, "linkedin_url": { "type": [ "string", "null" ], "description": "LinkedIn company page URL." }, "linkedin_id": { "type": [ "number", "null" ], "description": "LinkedIn numeric company ID." }, "location": { "type": [ "string", "null" ], "description": "Company headquarters location." }, "phone": { "type": [ "string", "null" ], "description": "Company phone number." }, "description": { "type": [ "string", "null" ], "description": "Company description." }, "is_client": { "type": "boolean", "description": "True if company is a client." }, "do_not_contact": { "type": "boolean", "description": "True if flagged do-not-contact." }, "do_not_contact_metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Do-not-contact metadata." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent update." }, "updated_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who last updated this company. Null if the last update came from a system/automated process." }, "date_of_last_engagement": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent engagement." }, "client_status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Client status UUID." }, "name": { "type": "string", "description": "Client status label (e.g. \"Active\", \"Prospect\", \"Former Client\")." } }, "required": [ "id", "name" ], "description": "Current client lifecycle status. Null if not a client." }, "enriched_company": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Enriched company UUID." }, "name": { "type": "string", "description": "Enriched company name." }, "domain": { "type": [ "string", "null" ], "description": "Enriched domain." }, "linkedin_url": { "type": [ "string", "null" ], "description": "Enriched LinkedIn URL." } }, "required": [ "id", "name", "domain", "linkedin_url" ], "description": "Enriched company data snapshot." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ] }, "description": "Team members who own this company." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom field values. Included when include contains \"custom_fields\"." } }, "required": [ "id", "name", "domain", "linkedin_url", "linkedin_id", "location", "phone", "description", "is_client", "do_not_contact", "do_not_contact_metadata", "created_at", "updated_at", "updated_by", "date_of_last_engagement", "client_status", "enriched_company", "owners" ] }, "UpdateCompanyRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name." }, "domain": { "type": "string", "description": "Website domain." }, "linkedin_url": { "type": "string", "description": "LinkedIn company page URL." }, "description": { "type": "string", "description": "Company description." }, "location": { "type": "string", "description": "Company headquarters location." }, "phone": { "type": "string", "description": "Company phone number." }, "is_client": { "type": "boolean", "description": "Whether to mark the company as a client." }, "client_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client status UUID, or null to clear. Use GET /v1/companies/statuses to get available status IDs. Setting a status automatically marks the company as a client." }, "do_not_contact": { "type": "boolean", "description": "Set to true to mark this company as do-not-contact (blocks outreach to anyone whose current company is this one), or false to clear the flag." }, "do_not_contact_reason": { "type": "string", "description": "Free-text reason for the do-not-contact flag (e.g. \"Active client — protect from sourcing\"). Only meaningful when do_not_contact is true. When omitted, any existing reason is preserved." }, "do_not_contact_expiration_date": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when do-not-contact should automatically expire. Only meaningful when do_not_contact is true. Pass an explicit date to set a custom expiration, or null for an indefinite do-not-contact. When omitted on a NEW do-not-contact flag, the team default from auth_organization_settings.auto_dnc_company_on_search_days is used (computed as that many days from now); if no default is configured, the do-not-contact is indefinite. When omitted on an existing do-not-contact flag, the current expiration is preserved." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to set as the company owners. Replaces all current owners. Pass an empty array to remove all owners. Omit to leave owners unchanged. Get IDs from GET /v1/team-members." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/companies." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/companies." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all existing values for this multi-select, multi-team-member, or multi-company attribute." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to update. Get attribute definitions from GET /v1/custom-fields/companies." } } }, "UpdateCompanyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "success", "data" ] }, "CompanyByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CompanyDetail" } }, "required": [ "success", "data" ] }, "CompanyDocumentTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDocumentType" } } }, "required": [ "success", "data" ] }, "CompanyDocumentType": { "type": "object", "properties": { "type": { "type": "string", "description": "Document type key." }, "name": { "type": "string", "description": "Document type display name." } }, "required": [ "type", "name" ] }, "CompanyDocumentsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDocument" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CompanyDocument": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document was uploaded." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document was last updated." }, "type": { "type": "string", "description": "Team-defined document type key." }, "title": { "type": [ "string", "null" ], "description": "Document title or filename." }, "link": { "type": "string", "description": "Document link. Stored-file links are short-lived and should be re-fetched after they expire." }, "text_content": { "type": [ "string", "null" ], "description": "Extracted plain-text document content. Included only when include_text=true and text is available." }, "char_count": { "type": "number", "description": "Number of characters returned in text_content. Included only when include_text=true." }, "truncated": { "type": "boolean", "description": "Whether text_content was truncated due to response size limits. Included only when include_text=true." } }, "required": [ "created_at", "updated_at", "type", "title", "link" ] }, "CompanyDocumentUploadMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload. Allowed types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB." }, "title": { "type": "string", "description": "Document title. Defaults to the original filename if omitted." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values: pitch_deck, legal, marketing, job_description, fee_agreement, offer_letter, client_information, compensation_information, other. Teams may add custom values." } }, "required": [ "file", "type" ] }, "CompanyDocumentUploadRequest": { "type": "object", "properties": { "file_url": { "type": "string", "format": "uri", "description": "Publicly accessible HTTPS URL of the file to download and attach to the company. The file must be 25 MB or smaller." }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Document title or filename. Defaults to the downloaded filename." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values: pitch_deck, legal, marketing, job_description, fee_agreement, offer_letter, client_information, compensation_information, other. Teams may add custom values." } }, "required": [ "file_url", "type" ] }, "CompanyDocumentUploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created document UUID." }, "created_at": { "type": "string", "description": "ISO 8601 upload timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." }, "type": { "type": "string", "description": "Team-defined document type key." }, "title": { "type": [ "string", "null" ], "description": "Document title or filename." }, "link": { "type": "string", "description": "Short-lived signed download URL. Re-fetch the document after this link expires." } }, "required": [ "id", "created_at", "updated_at", "type", "title", "link" ] } }, "required": [ "success", "data" ] }, "ListCompanyActivityTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyActivityTypeItem" } } }, "required": [ "success", "data" ] }, "CompanyActivityTypeItem": { "type": "object", "properties": { "type": { "type": "string", "description": "Activity type key. Use this value as `activity_type` when creating company activities or filtering list responses." }, "name": { "type": "string", "description": "Human-readable label for the activity type." }, "protected": { "type": "boolean", "description": "True when the type is a built-in system type that cannot be deleted." }, "is_archived": { "type": "boolean", "description": "True when the type has been hidden from the UI; archived types are excluded by default." } }, "required": [ "type", "name", "protected", "is_archived" ] }, "AddCompanyActivityRequest": { "type": "object", "properties": { "organization_company_id": { "type": "string", "format": "uuid", "description": "Company UUID to attach the activity to. Get from POST /v1/companies/search or GET /v1/companies/{id}." }, "activity_type": { "type": "string", "minLength": 1, "description": "Activity type key registered for the team. Must match an entry from GET /v1/company-activities/types (e.g. `secondary_note`, `call_note`, `meeting_note`, `email`, plus any custom types defined under Settings → Activity Types)." }, "activity_content": { "type": "string", "description": "Activity body. Plain text or HTML — HTML is auto-detected and stored alongside the plain-text mirror." } }, "required": [ "organization_company_id", "activity_type", "activity_content" ] }, "AddCompanyActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AddCompanyActivityResponseData" } }, "required": [ "success", "data" ] }, "AddCompanyActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created company activity UUID." }, "organization_company_id": { "type": "string", "format": "uuid", "description": "Company UUID the activity was attached to." }, "activity_type": { "type": "string", "description": "Activity type that was created." } }, "required": [ "id", "organization_company_id", "activity_type" ] }, "ListCompanyActivitiesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyActivityResponseData" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "CompanyActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity UUID." }, "organization_company_id": { "type": "string", "format": "uuid", "description": "Company UUID this activity belongs to." }, "activity_type": { "type": "string", "description": "Activity type key." }, "activity_content": { "type": "string", "description": "Activity body as HTML." }, "activity_raw_content": { "type": "string", "description": "Activity body as plain text." }, "is_starred": { "type": "boolean", "description": "True when the activity is pinned/starred." }, "created_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who created the activity, if any." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "organization_company_id", "activity_type", "activity_content", "activity_raw_content", "is_starred", "created_by", "created_at", "updated_at" ] }, "GetCompanyActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CompanyActivityResponseData" } }, "required": [ "success", "data" ] }, "UpdateCompanyActivityBody": { "type": "object", "properties": { "activity_content": { "type": "string", "description": "New content for the company activity. Format depends on content_type." }, "content_type": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Format of activity_content. \"text\" for plain text (auto-converted to HTML), \"html\" for raw HTML." } }, "required": [ "activity_content" ] }, "UpdateCompanyActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Updated company activity UUID." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." } }, "required": [ "id", "updated_at" ] } }, "required": [ "success", "data" ] }, "CompanyInsight": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Insight UUID." }, "organization_company_id": { "type": "string", "format": "uuid", "description": "Company this insight is attached to." }, "content": { "type": "string", "description": "Compact fact (under ~12 words), e.g. \"May 2026 rev: $100M ARR\"." }, "category": { "type": "string", "enum": [ "financials", "funding_ma", "team", "talent", "customers", "product", "tech", "gtm", "competitive", "culture", "other" ], "description": "Subject-based category of the fact." }, "topic": { "type": "string", "description": "Short slug for the topic the fact is about (e.g. revenue, headcount, cto)." }, "observation_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when the fact was observed." }, "status": { "type": "string", "enum": [ "active", "dismissed" ], "description": "Whether the insight is active or dismissed." }, "is_user_edited": { "type": "boolean", "description": "True if a teammate has edited this insight after creation." }, "source_activity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Activity that produced this insight." }, "source_person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Person whose note/transcript was the source." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "organization_company_id", "content", "category", "topic", "observation_date", "status", "is_user_edited", "source_activity_id", "source_person_id", "created_at", "updated_at" ] }, "CustomFieldDefinitionsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinition" } } }, "required": [ "success", "data" ] }, "CustomFieldDefinition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Use as attribute_id in search filters (select_attribute_filters, numeric_attribute_filters, etc.) and in custom field updates." }, "name": { "type": "string", "description": "Attribute display name (e.g. \"Tags\", \"Seniority Level\", \"Years of Experience\")." }, "description": { "type": [ "string", "null" ], "description": "Attribute description explaining its intended use." }, "data_type": { "type": "string", "enum": [ "string", "integer", "decimal", "multi-select", "single-select", "boolean", "date", "multi-team-member", "multi-company", "url" ], "description": "Attribute data type. Determines which filter type to use: string/url → text match, integer/decimal → numeric_attribute_filters, date → date_attribute_filters, single-select/multi-select → select_attribute_filters, multi-team-member → team_member_attribute_filters, multi-company → company_attribute_filters, boolean → select_attribute_filters." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this attribute is scoped to. Null for global (person-level) attributes. Job-specific attributes apply only when the person is a candidate on that job." }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "description": "List UUID this attribute is scoped to. Null for global (person-level) attributes." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag option UUID. Use this ID in select_attribute_filters → values when filtering by this tag." }, "name": { "type": "string", "description": "Tag display name (e.g. \"Senior\", \"Banking\", \"High Priority\")." }, "color": { "type": [ "string", "null" ], "description": "Hex color code for UI display (e.g. \"#86efac\")." }, "description": { "type": [ "string", "null" ], "description": "Optional tag description." } }, "required": [ "id", "name", "color", "description" ] }, "description": "Available tag options for select-type attributes. Empty array for non-select types." } }, "required": [ "id", "name", "description", "data_type", "job_id", "list_id", "tags" ] }, "AddDealActivityRequest": { "type": "object", "properties": { "deal_id": { "type": "string", "format": "uuid", "description": "Deal UUID to attach the activity to. Get from POST /v1/deals/search or GET /v1/deals/{id}." }, "activity_type": { "type": "string", "minLength": 1, "description": "Activity type key. Standard values: `secondary_note` (general note), `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for deals." }, "activity_content": { "type": "string", "description": "Activity body. Plain text or HTML — HTML is auto-detected and stored alongside the plain-text mirror." } }, "required": [ "deal_id", "activity_type", "activity_content" ] }, "AddDealActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AddDealActivityResponseData" } }, "required": [ "success", "data" ] }, "AddDealActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created deal activity UUID." }, "deal_id": { "type": "string", "format": "uuid", "description": "Deal UUID the activity was attached to." }, "activity_type": { "type": "string", "description": "Activity type that was created." } }, "required": [ "id", "deal_id", "activity_type" ] }, "ListDealActivitiesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DealActivityResponseData" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "DealActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity UUID." }, "deal_id": { "type": "string", "format": "uuid", "description": "Deal UUID this activity belongs to." }, "activity_type": { "type": "string", "description": "Activity type key." }, "activity_content": { "type": "string", "description": "Activity body as HTML." }, "activity_raw_content": { "type": "string", "description": "Activity body as plain text." }, "is_starred": { "type": "boolean", "description": "True when the activity is pinned/starred." }, "created_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who created the activity, if any." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "deal_id", "activity_type", "activity_content", "activity_raw_content", "is_starred", "created_by", "created_at", "updated_at" ] }, "GetDealActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DealActivityResponseData" } }, "required": [ "success", "data" ] }, "UpdateDealActivityBody": { "type": "object", "properties": { "activity_content": { "type": "string", "description": "New content for the deal activity. Format depends on content_type." }, "content_type": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Format of activity_content. \"text\" for plain text (auto-converted to HTML), \"html\" for raw HTML." } }, "required": [ "activity_content" ] }, "UpdateDealActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Updated deal activity UUID." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." } }, "required": [ "id", "updated_at" ] } }, "required": [ "success", "data" ] }, "DealStatusesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DealStatusItem" } } }, "required": [ "success", "data" ] }, "DealStatusItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal status UUID." }, "name": { "type": "string", "description": "Status name." }, "color": { "type": [ "string", "null" ], "description": "Hex color code." }, "stage_order": { "type": [ "number", "null" ], "description": "Display order within the pipeline." }, "status_type": { "type": "string", "enum": [ "active", "won", "lost" ], "description": "Status category: active, won, or lost." }, "is_default_status": { "type": "boolean", "description": "Whether this is the default status for new deals." }, "default_win_probability": { "type": [ "integer", "null" ], "description": "Win probability (0–100) applied when a deal enters this status. Won statuses always apply 100 and lost statuses 0. Null means deals keep their current probability." }, "rotting_days": { "type": [ "integer", "null" ], "description": "Days an open deal can stay in this status before it counts as rotting. Null means the organization default applies." }, "effective_rotting_days": { "type": [ "integer", "null" ], "description": "Rotting period in effect for this status: its own value, else the organization default. Null for won and lost statuses, or when rotting is off." } }, "required": [ "id", "name", "color", "stage_order", "status_type", "is_default_status", "default_win_probability", "rotting_days", "effective_rotting_days" ] }, "DealsSearchBody": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records to return (1–100). Defaults to 100." }, "sort_by": { "type": "string", "description": "Column to sort by. Accepted values:\n- `name` — deal name (alphabetical)\n- `amount` — deal monetary amount\n- `win_probability` — win probability percentage\n- `company` — client company name (alphabetical)\n- `status` — deal status (by stage order)\n- `closed_date` — expected or actual close date\n- `open_date` — deal open date\n- `last_contacted_at` — most recent engagement with client contacts\n- `created_at` — creation timestamp (default)\n- `custom_` — any custom attribute UUID prefixed with `custom_` (e.g. `custom_e5f6a7b8-...`). Sorts by the attribute's decimal, date, string, or tag value." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Full-text search across deal name, client company name, and domain. Multiple keywords use OR logic." }, "deal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Pre-filter to a specific set of deal UUIDs." }, "list_id": { "type": "string", "format": "uuid", "description": "Filter to deals belonging to this list." }, "deal_status_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only deals with these status UUIDs." }, "deal_status_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude deals with these status UUIDs." }, "owner_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only deals owned by these team members. Get IDs from GET /v1/team-members." }, "owner_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude deals owned by these team members." }, "show_open_deals_only": { "type": "boolean", "description": "When true, only return deals with an \"active\" status type." }, "show_archived": { "type": "boolean", "description": "When true, return archived (soft-deleted) deals instead of active ones." }, "closed_date_filter": { "type": "object", "properties": { "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include deals with no value set for this date field." } }, "description": "Filter by closed_date range. Supports start_date, end_date, and include_empty." }, "open_date_filter": { "type": "object", "properties": { "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include deals with no value set for this date field." } }, "description": "Filter by open_date range. Supports start_date, end_date, and include_empty." }, "select_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions." }, "excluded_values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/deals." }, "numeric_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}." }, "min": { "type": [ "number", "null" ], "description": "Minimum value (inclusive). Null for no lower bound." }, "max": { "type": [ "number", "null" ], "description": "Maximum value (inclusive). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/deals." }, "date_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}." }, "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/deals." }, "team_member_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to include. Get IDs from GET /v1/team-members." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified team members (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no team member assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/deals." }, "company_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-company type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to include. Get IDs from GET /v1/companies/search or search-companies." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified companies (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no company assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by multi-company custom fields. Get attribute_id from GET /v1/custom-fields/deals." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "client_contacts" ] }, "description": "Extra sections to embed. Values: custom_fields, client_contacts. Omit for base fields only. client_contacts are absent unless explicitly requested." } } }, "DealsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "Deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique deal UUID." }, "name": { "type": "string", "description": "Deal name." }, "amount": { "type": [ "number", "null" ], "description": "Deal monetary amount — the fee the firm invoices the client." }, "currency_code": { "type": "string", "description": "ISO 4217 currency code for the deal amount (e.g. USD, EUR, GBP). Defaults to the organization setting or USD." }, "compensation": { "type": [ "number", "null" ], "description": "Candidate's expected total annual compensation (salary + bonus + equity). Used to compute the deal amount. Omitted for API-key callers without compensation:read." }, "compensation_currency_code": { "type": "string", "description": "ISO 4217 currency code for the estimated compensation. May differ from currency_code when the candidate is paid in a different currency than the firm invoices in. Defaults to the organization setting or USD. Omitted for API-key callers without compensation:read." }, "pricing_rate": { "type": [ "number", "null" ], "description": "Recruitment fee percentage (0–100) charged to the client on a successful placement." }, "win_probability": { "type": [ "number", "null" ], "description": "Probability of winning the deal (0–100)." }, "closed_date": { "type": [ "string", "null" ], "description": "ISO 8601 expected or actual close date." }, "open_date": { "type": "string", "format": "date", "description": "Date the deal was opened (YYYY-MM-DD)." }, "last_contacted_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of last contact with deal client contacts." }, "deal_status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal status UUID. Use for deal_status_ids_included/excluded filters." }, "name": { "type": "string", "description": "Human-readable status name (e.g. \"Proposal Sent\", \"Closed Won\")." } }, "required": [ "id", "name" ], "description": "Current deal status with id and name. Null if no status assigned." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." }, "client_name": { "type": [ "string", "null" ], "description": "Client company name." }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client company UUID." }, "deal_lost_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Selected lost reason UUID, if this deal was lost." }, "deal_lost_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was lost." }, "deal_lost_reason": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal reason UUID." }, "reason": { "type": "string", "description": "Human-readable deal reason." } }, "required": [ "id", "reason" ], "description": "Selected lost reason details, if this deal was lost." }, "deal_won_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Selected won reason UUID, if this deal was won." }, "deal_won_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was won." }, "deal_won_reason": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal reason UUID." }, "reason": { "type": "string", "description": "Human-readable deal reason." } }, "required": [ "id", "reason" ], "description": "Selected won reason details, if this deal was won." }, "next_task": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Task UUID. Use GET /v1/tasks/{id} for full task details." }, "title": { "type": [ "string", "null" ], "description": "Task text, up to 200 characters." }, "task_type": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ], "description": "Task type." }, "due_date": { "type": [ "string", "null" ], "description": "ISO 8601 due date and time." } }, "required": [ "id", "title", "task_type", "due_date" ], "description": "The open task on this deal with the earliest due date. Null when the deal has no open task. Omitted for API-key callers without tasks:read." }, "open_task_count": { "type": "integer", "description": "Number of open tasks on this deal. Omitted for API-key callers without tasks:read." }, "stage_entered_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the deal entered its current status. Falls back to the creation time when no status history exists." }, "days_in_stage": { "type": [ "integer", "null" ], "description": "Whole days the deal has been in its current status. Null for won or lost deals." }, "is_rotting": { "type": "boolean", "description": "True when an open deal has been in its status longer than the status's rotting period (or the organization default)." }, "needs_attention": { "type": "boolean", "description": "True when an open deal is rotting or its next task is overdue. Omitted for API-key callers without tasks:read." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": [ "string", "null" ], "description": "Team member full name." } }, "required": [ "id", "name" ] }, "description": "Deal owners." }, "client_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/DealClientContact" }, "description": "Client contacts linked directly to this deal via deal_client_contacts. On search, included only when include contains \"client_contacts\". Resolved exclusively from deal links — not inferred from the deal client company." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom attribute values. Included when include contains \"custom_fields\"." } }, "required": [ "id", "name", "amount", "currency_code", "pricing_rate", "win_probability", "closed_date", "open_date", "last_contacted_at", "deal_status", "created_at", "client_name", "client_id", "deal_lost_reason_id", "deal_lost_reason_text", "deal_lost_reason", "deal_won_reason_id", "deal_won_reason_text", "deal_won_reason", "stage_entered_at", "days_in_stage", "is_rotting", "owners" ] }, "DealClientContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client contact UUID (`client_contacts.id`). Pass these in `client_contact_ids` when creating or updating a deal. This is not the deal_client_contacts junction-row UUID." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the person this contact represents. Use GET /v1/persons/{id} for full person details." }, "name": { "type": [ "string", "null" ], "description": "Contact's full name." }, "image_url": { "type": [ "string", "null" ], "description": "Contact's profile image URL." }, "job_title": { "type": [ "string", "null" ], "description": "Contact's current job title." }, "email": { "type": [ "string", "null" ], "description": "Preferred email address for this person, if any." }, "phone": { "type": [ "string", "null" ], "description": "Preferred phone number for this person, if any." } }, "required": [ "id", "person_id", "name", "image_url", "job_title", "email", "phone" ] }, "DealByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DealDetail" } }, "required": [ "success", "data" ] }, "DealDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique deal UUID." }, "name": { "type": "string", "description": "Deal name." }, "amount": { "type": [ "number", "null" ], "description": "Deal monetary amount — the fee the firm invoices the client." }, "currency_code": { "type": "string", "description": "ISO 4217 currency code for the deal amount (e.g. USD, EUR, GBP)." }, "compensation": { "type": [ "number", "null" ], "description": "Candidate's expected total annual compensation (salary + bonus + equity). Used to compute the deal amount. Omitted for API-key callers without compensation:read." }, "compensation_currency_code": { "type": "string", "description": "ISO 4217 currency code for the estimated compensation. May differ from currency_code. Omitted for API-key callers without compensation:read." }, "pricing_rate": { "type": [ "number", "null" ], "description": "Recruitment fee percentage (0–100) charged to the client on a successful placement." }, "win_probability": { "type": [ "number", "null" ], "description": "Probability of winning the deal (0–100)." }, "description": { "type": [ "string", "null" ], "description": "Free-text deal description." }, "closed_date": { "type": [ "string", "null" ], "description": "ISO 8601 expected or actual close date." }, "open_date": { "type": "string", "format": "date", "description": "Date the deal was opened (YYYY-MM-DD)." }, "deal_lost_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Selected lost reason UUID, if this deal was lost." }, "deal_lost_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was lost." }, "deal_lost_reason": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal reason UUID." }, "reason": { "type": "string", "description": "Human-readable deal reason." } }, "required": [ "id", "reason" ], "description": "Selected lost reason details, if this deal was lost." }, "deal_won_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Selected won reason UUID, if this deal was won." }, "deal_won_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was won." }, "deal_won_reason": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal reason UUID." }, "reason": { "type": "string", "description": "Human-readable deal reason." } }, "required": [ "id", "reason" ], "description": "Selected won reason details, if this deal was won." }, "referred_by": { "type": [ "string", "null" ], "description": "Person UUID of the referrer ." }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs of jobs linked to this deal via the deal_jobs table." }, "client_id": { "type": [ "string", "null" ], "description": "Associated client company UUID." }, "client_name": { "type": [ "string", "null" ], "description": "Client company name." }, "deal_status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Deal status UUID. Use for deal_status_ids_included/excluded filters." }, "name": { "type": "string", "description": "Human-readable status name (e.g. \"Proposal Sent\", \"Closed Won\")." } }, "required": [ "id", "name" ], "description": "Current deal status with id and name. Null if no status assigned." }, "is_archived": { "type": "boolean", "description": "True if the deal has been archived." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 last-updated timestamp." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": [ "string", "null" ], "description": "Team member full name." } }, "required": [ "id", "name" ] }, "description": "Deal owners." }, "client_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/DealClientContact" }, "description": "Client contacts linked directly to this deal via deal_client_contacts. Always returned (empty array when none are linked). Resolved exclusively from deal links — not inferred from the deal client company. `id` is the client_contacts UUID." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom attribute values. Included when include contains \"custom_fields\"." } }, "required": [ "id", "name", "amount", "currency_code", "pricing_rate", "win_probability", "description", "closed_date", "open_date", "deal_lost_reason_id", "deal_lost_reason_text", "deal_lost_reason", "deal_won_reason_id", "deal_won_reason_text", "deal_won_reason", "referred_by", "job_ids", "client_id", "client_name", "deal_status", "is_archived", "created_at", "updated_at", "owners", "client_contacts" ] }, "DealUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Deal name." }, "client_id": { "type": "string", "format": "uuid", "description": "Client company UUID." }, "amount": { "type": "number", "description": "Deal amount." }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g. USD, EUR, GBP)." }, "compensation": { "type": "number", "minimum": 0, "description": "Candidate's expected total annual compensation." }, "compensation_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code for compensation." }, "pricing_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Recruitment fee percentage (0–100)." }, "win_probability": { "type": "number", "minimum": 0, "maximum": 100, "description": "Win probability (0–100). When deal_status_id changes and win_probability is omitted or equal to its current value, it is reset from the new status: 100 for won, 0 for lost, otherwise the status's default_win_probability. Send a different value to keep your own." }, "deal_status_id": { "type": "string", "format": "uuid", "description": "Deal status UUID. Changing it can also update win_probability (see win_probability)." }, "description": { "type": "string", "description": "Description." }, "closed_date": { "type": [ "string", "null" ], "description": "ISO 8601 close date. Pass null to clear." }, "open_date": { "type": "string", "format": "date", "description": "Deal opening date (YYYY-MM-DD)." }, "deal_lost_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Lost reason UUID from deal_lost_reasons. Pass null to clear the selected lost reason." }, "deal_lost_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was lost. Pass null to clear." }, "deal_won_reason_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Won reason UUID from deal_won_reasons. Pass null to clear the selected won reason." }, "deal_won_reason_text": { "type": [ "string", "null" ], "description": "Additional notes explaining why the deal was won. Pass null to clear." }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Job UUIDs to link to this deal. Replaces all existing deal_jobs links." }, "referred_by": { "type": "string", "format": "uuid", "description": "Person UUID of the referrer." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to assign as deal owners. Replaces all existing deal_owners links. Pass an empty array to remove all owners." }, "client_contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Client contact UUIDs to attach as deal contacts. Replaces all existing deal_client_contacts links. Pass an empty array to detach all contacts. Each contact must belong to this team." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/deals." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/deals." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all values for this attribute before applying adds." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to update." }, "is_archived": { "type": "boolean", "description": "Set true to archive the deal, false to unarchive." } } }, "DealUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "success", "data" ] }, "DealCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Deal name (required)." }, "client_id": { "type": "string", "format": "uuid", "description": "Client company UUID." }, "client_linkedin_url": { "type": "string", "format": "uri", "description": "Client company LinkedIn URL. Used to look up or create the client company if client_id is not provided." }, "amount": { "type": "number", "description": "Deal amount — the fee the firm invoices the client." }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g. USD, EUR, GBP). Defaults to the organization setting or USD." }, "compensation": { "type": "number", "minimum": 0, "description": "Candidate's expected total annual compensation." }, "compensation_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code for compensation. Defaults to currency_code (or the organization default / USD)." }, "pricing_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Recruitment fee percentage (0–100)." }, "win_probability": { "type": "number", "minimum": 0, "maximum": 100, "description": "Win probability (0–100). If omitted, it is set from the deal status: 100 for won, 0 for lost, otherwise the status's default_win_probability (see List deal statuses)." }, "deal_status_id": { "type": "string", "format": "uuid", "description": "Deal status UUID. Use List deal statuses endpoint to get the UUID." }, "description": { "type": "string", "description": "Description." }, "closed_date": { "type": "string", "description": "ISO 8601 expected or actual close date." }, "open_date": { "type": "string", "format": "date", "description": "Deal opening date (YYYY-MM-DD). Defaults to the deal's creation date." }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Job UUIDs to link to this deal. Creates entries in the deal_jobs table." }, "referred_by": { "type": "string", "format": "uuid", "description": "Person UUID of the referrer." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to assign as deal owners. If omitted, the caller is auto-assigned when authenticated as a team member." }, "client_contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Client contact UUIDs to attach as deal contacts. Get IDs from GET /v1/client-contacts or by creating contacts via POST /v1/client-contacts. Each contact must belong to this team. When omitted, the deal is created with no contacts attached." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/deals." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/deals." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all values for this attribute before applying adds." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to set on creation." } }, "required": [ "name" ] }, "DealCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DealCreateResponseData" } }, "required": [ "success", "data" ] }, "DealCreateResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created deal UUID." }, "name": { "type": "string", "description": "Deal name." }, "amount": { "type": [ "number", "null" ], "description": "Deal amount." }, "currency_code": { "type": "string", "description": "ISO 4217 currency code." }, "compensation": { "type": [ "number", "null" ], "description": "Candidate's expected total annual compensation. Omitted for API-key callers without compensation:read." }, "compensation_currency_code": { "type": "string", "description": "ISO 4217 currency code for compensation. Omitted for API-key callers without compensation:read." }, "pricing_rate": { "type": [ "number", "null" ], "description": "Recruitment fee percentage (0–100)." }, "win_probability": { "type": [ "number", "null" ], "description": "Win probability." }, "deal_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Deal status UUID." }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client company UUID." }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs of jobs linked to this deal." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs assigned as deal owners." }, "client_contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Client contact UUIDs attached to this deal as deal contacts." }, "open_date": { "type": "string", "format": "date", "description": "Date the deal was opened (YYYY-MM-DD)." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." } }, "required": [ "id", "name", "amount", "currency_code", "pricing_rate", "win_probability", "deal_status_id", "client_id", "job_ids", "owner_ids", "client_contact_ids", "open_date", "created_at" ] }, "FeeStatusesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeeStatus" } } }, "required": [ "success", "data" ] }, "FeeStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Fee status UUID." }, "name": { "type": "string", "description": "Status name shown in the app (e.g. \"Invoiced\")." }, "status_type": { "type": "string", "enum": [ "pending", "invoiced", "paid", "cancelled" ], "description": "Lifecycle category of the status: `pending`, `invoiced`, `paid` or `cancelled`. Revenue reports count `paid` fees as collected." }, "color": { "type": "string", "description": "Hex color code of the status badge." }, "position": { "type": "number", "description": "Display order of the status, lowest first." }, "is_default": { "type": "boolean", "description": "Whether new retainers, milestones and placements start in this status." } }, "required": [ "id", "name", "status_type", "color", "position", "is_default" ] }, "AddJobActivityRequest": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID to attach the activity to. Get from POST /v1/jobs/search or GET /v1/jobs/{id}." }, "activity_type": { "type": "string", "minLength": 1, "description": "Activity type key. Standard values: `secondary_note` (general note), `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for jobs." }, "activity_content": { "type": "string", "description": "Activity body. Plain text or HTML — HTML is auto-detected and stored alongside the plain-text mirror." } }, "required": [ "job_id", "activity_type", "activity_content" ] }, "AddJobActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AddJobActivityResponseData" } }, "required": [ "success", "data" ] }, "AddJobActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created job activity UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID the activity was attached to." }, "activity_type": { "type": "string", "description": "Activity type that was created." } }, "required": [ "id", "job_id", "activity_type" ] }, "ListJobActivitiesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobActivityResponseData" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID this activity belongs to." }, "activity_type": { "type": "string", "description": "Activity type key." }, "activity_content": { "type": "string", "description": "Activity body as HTML." }, "activity_raw_content": { "type": "string", "description": "Activity body as plain text." }, "is_starred": { "type": "boolean", "description": "True when the activity is pinned/starred." }, "created_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who created the activity, if any." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "job_id", "activity_type", "activity_content", "activity_raw_content", "is_starred", "created_by", "created_at", "updated_at" ] }, "GetJobActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobActivityResponseData" } }, "required": [ "success", "data" ] }, "UpdateJobActivityBody": { "type": "object", "properties": { "activity_content": { "type": "string", "description": "New content for the job activity. Format depends on content_type." }, "content_type": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Format of activity_content. \"text\" for plain text (auto-converted to HTML), \"html\" for raw HTML." } }, "required": [ "activity_content" ] }, "UpdateJobActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Updated job activity UUID." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." } }, "required": [ "id", "updated_at" ] } }, "required": [ "success", "data" ] }, "JobOfferStatusesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobOfferStatusItem" } } }, "required": [ "success", "data" ] }, "JobOfferStatusItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Offer status UUID." }, "name": { "type": "string", "description": "Status name." }, "color": { "type": [ "string", "null" ], "description": "Hex color code." }, "stage_order": { "type": [ "number", "null" ], "description": "Display order of the status." }, "status_type": { "type": "string", "enum": [ "pending", "accepted", "rejected", "rescinded" ], "description": "Lifecycle category of the status: pending, accepted, rejected, or rescinded." }, "is_default_status": { "type": "boolean", "description": "Whether this is the default status for new offers." } }, "required": [ "id", "name", "color", "stage_order", "status_type", "is_default_status" ] }, "JobOffersListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobOfferListItem" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobOfferListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Offer UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "job_name": { "type": [ "string", "null" ], "description": "Job title." }, "job_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client company UUID for the job." }, "job_company_name": { "type": [ "string", "null" ], "description": "Client company name for the job." }, "candidate_id": { "type": "string", "format": "uuid", "description": "Candidate record UUID (the person on this job)." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the person who received the offer." }, "person_name": { "type": [ "string", "null" ], "description": "Name of the person who received the offer." }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Offer status UUID." }, "name": { "type": "string", "description": "Status name (e.g. \"Verbal Accept\")." }, "color": { "type": [ "string", "null" ], "description": "Hex color code." }, "status_type": { "type": "string", "enum": [ "pending", "accepted", "rejected", "rescinded" ], "description": "Lifecycle category of the status: pending, accepted, rejected, or rescinded." } }, "required": [ "id", "name", "color", "status_type" ], "description": "Current offer status. Null if no status is set." }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/JobOfferOwner" }, "description": "Team members credited on the offer, in the order they were added. Empty if none." }, "client_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/JobOfferClientContact" }, "description": "Client contacts attached to the offer, in the order they were added. Deleted contacts are omitted. Empty if none." }, "extended_date": { "type": [ "string", "null" ], "description": "ISO 8601 date the offer was extended." }, "accepted_date": { "type": [ "string", "null" ], "description": "ISO 8601 date the offer was accepted." }, "candidate_start_date": { "type": [ "string", "null" ], "description": "ISO 8601 anticipated start date." }, "compensation_currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code. Omitted for API-key callers without the `compensation:read` scope." }, "compensation_base": { "type": [ "number", "null" ], "description": "Base salary offered. Omitted for API-key callers without the `compensation:read` scope." }, "compensation_bonus": { "type": [ "number", "null" ], "description": "Bonus offered: a cash amount or a percentage of base, per `bonus_type`. Omitted for API-key callers without the `compensation:read` scope." }, "bonus_type": { "type": [ "string", "null" ], "enum": [ "fixed", "percent" ], "description": "Whether `compensation_bonus` is a fixed amount or a percent of base. Omitted for API-key callers without the `compensation:read` scope." }, "annual_equity_grant_percent": { "type": [ "number", "null" ], "description": "Annual equity grant, as a percent. Omitted for API-key callers without the `compensation:read` scope." }, "annual_equity_grant_amount": { "type": [ "number", "null" ], "description": "Annual equity grant amount. Omitted for API-key callers without the `compensation:read` scope." }, "initial_equity_grant_percent": { "type": [ "number", "null" ], "description": "Initial equity grant, as a percent. Omitted for API-key callers without the `compensation:read` scope." }, "initial_equity_grant_amount": { "type": [ "number", "null" ], "description": "Initial equity grant amount. Omitted for API-key callers without the `compensation:read` scope." }, "relocation_bonus": { "type": [ "number", "null" ], "description": "Relocation bonus amount. Omitted for API-key callers without the `compensation:read` scope." }, "sign_on_bonus": { "type": [ "number", "null" ], "description": "One-time sign-on bonus amount. Omitted for API-key callers without the `compensation:read` scope." }, "total_estimated_compensation": { "type": [ "number", "null" ], "description": "Total estimated compensation. Omitted for API-key callers without the `compensation:read` scope." }, "note": { "type": [ "string", "null" ], "description": "Offer notes." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "job_id", "job_name", "job_company_id", "job_company_name", "candidate_id", "person_id", "person_name", "status", "owners", "client_contacts", "extended_date", "accepted_date", "candidate_start_date", "note", "created_at", "updated_at" ] }, "JobOfferOwner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": [ "string", "null" ], "description": "Team member full name." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." }, "image_url": { "type": [ "string", "null" ], "description": "Team member profile image URL." } }, "required": [ "id", "name", "first_name", "last_name", "image_url" ] }, "JobOfferClientContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client contact UUID (`client_contacts.id`), not the junction-row UUID." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the person this contact represents. Use GET /v1/persons/{id} for contact details." }, "name": { "type": [ "string", "null" ], "description": "Contact's full name." }, "first_name": { "type": [ "string", "null" ], "description": "Contact's first name." }, "last_name": { "type": [ "string", "null" ], "description": "Contact's last name." }, "image_url": { "type": [ "string", "null" ], "description": "Contact's profile image URL." } }, "required": [ "id", "person_id", "name", "first_name", "last_name", "image_url" ] }, "JobsListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobBase" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobBase": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job UUID. Use in GET /v1/jobs/{id} for full details with pipeline stages." }, "name": { "type": "string", "description": "Job title." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "is_archived": { "type": "boolean", "description": "True if the job has been archived." }, "client_company_name": { "type": [ "string", "null" ], "description": "Client company name." }, "client_company_id": { "type": [ "string", "null" ], "description": "Client company UUID. Matches IDs from GET /v1/companies." }, "client_company_domain": { "type": [ "string", "null" ], "description": "Client company website domain (e.g. \"acme.com\")." }, "client_company_linkedin_url": { "type": [ "string", "null" ], "description": "Client company LinkedIn URL." }, "job_status_name": { "type": [ "string", "null" ], "description": "Current job status label (e.g. \"Active\", \"On Hold\", \"Closed\")." }, "job_status_id": { "type": [ "string", "null" ], "description": "Job status UUID. Use in job_status_ids_included/excluded filters in POST /v1/jobs/search." }, "job_status_type": { "type": [ "string", "null" ], "enum": [ "not_started", "in_progress", "closed_won", "closed_lost" ], "description": "Lifecycle category of the current job status: not_started, in_progress, closed_won, or closed_lost. Independent of the custom status name. Null when the job has no status." }, "candidate_count": { "type": "number", "description": "Total number of active candidates in this job. Excludes archived candidacies and candidates whose person is archived." }, "location": { "type": [ "string", "null" ], "description": "Job location (e.g. \"New York, NY\" or \"Remote\")." }, "primary_url": { "type": [ "string", "null" ], "description": "Primary job posting URL." }, "job_function": { "type": [ "string", "null" ], "description": "Department or function (e.g. \"Engineering\", \"Sales\", \"Marketing\")." }, "open_date": { "type": [ "string", "null" ], "description": "Date job opened (YYYY-MM-DD)." }, "end_date": { "type": [ "string", "null" ], "description": "Target close date (YYYY-MM-DD). Null if open-ended." }, "currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\")." }, "salary_range": { "type": [ "string", "null" ], "description": "Raw salary range with an exclusive upper bound — \"[150000,200001)\" means 150,000 to 200,000. Prefer salary_min and salary_max, which give the same bounds as plain inclusive numbers." }, "salary_min": { "type": [ "integer", "null" ], "description": "Minimum annual salary parsed from salary_range. Null when no range is set." }, "salary_max": { "type": [ "integer", "null" ], "description": "Maximum annual salary parsed from salary_range. Null when no range is set." }, "salary_details": { "type": [ "string", "null" ], "description": "Free-text salary details that complement the structured range (e.g. \"+ 0.5% equity, signing bonus negotiable\")." }, "billing_contact_name": { "type": [ "string", "null" ], "description": "Name of the client-side billing contact for this job (used on invoices)." }, "billing_contact_email": { "type": [ "string", "null" ], "description": "Email of the client-side billing contact for this job. Validated as an email on write." }, "fee": { "type": [ "number", "null" ], "description": "Manually entered forecasting fee stored on the job (used for pipeline/BD forecasting). This is NOT the fee tracked in the \"Fees and Placements\" section — for that, use the \"fees\" section (see fees.total_placement_fee)." }, "description": { "type": [ "string", "null" ], "description": "Plain-text job description." }, "team_members": { "type": "array", "items": { "$ref": "#/components/schemas/JobTeamMember" }, "description": "Team members assigned to this job with their roles." }, "client_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/JobClientContact" }, "description": "Client-side contacts assigned to this job (the \"Client Contacts\" field on the job). Always returned by GET /v1/jobs/{id}; on list and search, request it with \"client_contacts\" in the include parameter." }, "share_links": { "type": "array", "items": { "$ref": "#/components/schemas/JobShareLink" }, "description": "Active client-pipeline share links for this job (expired closed-job links are omitted). Always returned by GET /v1/jobs/{id}; on list and search, request it with \"share_links\" in the include parameter." }, "linked_deals": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedJobDeal" }, "description": "CRM deals linked to this job via the deal_jobs join table. This is separate from the \"Fees and Placements\" section — logging a placement or retainer does NOT create a linked deal. Included on GET /v1/jobs/{id}, and on list/search when \"linked_deals\" is in the include parameter. Omitted for API-key callers without deals:read." }, "fees": { "allOf": [ { "$ref": "#/components/schemas/JobFees" }, { "description": "Fee and placement data from the \"Fees and Placements\" section (retainer structure, placement/retainer/milestone billing events, and total placement fee). Included on GET /v1/jobs/{id}, and on list/search when \"fees\" is in the include parameter. Omitted for API-key callers without compensation:read." } ] }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom attribute values. Included when include contains \"custom_fields\". Definitions from GET /v1/custom-fields/jobs." }, "job_status_changes": { "type": "array", "items": { "$ref": "#/components/schemas/JobStatusChange" }, "description": "Recorded job status history, oldest first. Each entry is one stay in a status. Included on list, search, job detail, and create when include contains \"job_status_changes\". Omitted otherwise." } }, "required": [ "id", "name", "created_at", "is_archived", "client_company_name", "client_company_id", "client_company_domain", "client_company_linkedin_url", "job_status_name", "job_status_id", "job_status_type", "candidate_count", "location", "primary_url", "job_function", "open_date", "end_date", "currency_code", "salary_range", "salary_min", "salary_max", "salary_details", "billing_contact_name", "billing_contact_email", "fee", "description", "team_members" ] }, "JobTeamMember": { "type": "object", "properties": { "team_member_id": { "type": "string", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "email": { "type": [ "string", "null" ], "description": "Team member email address." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "role_id": { "type": [ "string", "null" ], "description": "Job team member role UUID. Get available roles from GET /v1/jobs/team-member-roles." }, "role_name": { "type": [ "string", "null" ], "description": "Role display name (e.g. \"Team Lead\", \"Executive Sponsor\")." } }, "required": [ "team_member_id", "email", "first_name", "last_name", "role_id", "role_name" ] }, "JobClientContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of this contact's assignment to the job." }, "client_contact_id": { "type": "string", "format": "uuid", "description": "Client contact UUID. Pass these in client_contact_ids when creating or updating a job." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the person this contact represents. Use GET /v1/persons/{id} for their email, phone, and title." }, "name": { "type": [ "string", "null" ], "description": "Contact's full name." } }, "required": [ "id", "client_contact_id", "person_id", "name" ] }, "JobShareLink": { "type": "object", "properties": { "id": { "type": "string", "description": "Share link ID used in the public URL path. This is a slug, not a UUID." }, "url": { "type": "string", "format": "uri", "description": "Public client-pipeline URL for this share link (https://stardex.com/share/{orgSlug}/{id})." }, "title": { "type": "string", "description": "Share link display title." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "requires_email_verification": { "type": "boolean", "description": "True if viewers must verify their email before opening the pipeline." }, "keep_active_when_job_closed": { "type": "boolean", "description": "True if this link stays publicly accessible after the job is closed. Closed-job links without this flag are omitted because they are expired." } }, "required": [ "id", "url", "title", "created_at", "requires_email_verification", "keep_active_when_job_closed" ] }, "LinkedJobDeal": { "type": "object", "properties": { "deal_id": { "type": "string", "format": "uuid", "description": "Deal UUID. Matches IDs from GET /v1/deals/{id} or POST /v1/deals/search." }, "deal_job_id": { "type": "string", "format": "uuid", "description": "UUID of the join row in the deal_jobs table linking this job to the deal." }, "name": { "type": "string", "description": "Deal name." }, "amount": { "type": [ "number", "null" ], "description": "Deal amount (fee invoiced to the client). Null if unset." }, "currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code for the deal amount (e.g. \"USD\")." }, "deal_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current deal status UUID, if any." }, "deal_status_name": { "type": [ "string", "null" ], "description": "Current deal status display name (e.g. \"Qualified\", \"Won\", \"Lost\")." }, "deal_status_color": { "type": [ "string", "null" ], "description": "Hex color of the deal status badge (e.g. \"#10B981\")." } }, "required": [ "deal_id", "deal_job_id", "name", "amount", "currency_code", "deal_status_id", "deal_status_name", "deal_status_color" ] }, "JobFees": { "type": "object", "properties": { "retainer": { "allOf": [ { "$ref": "#/components/schemas/JobRetainer" }, { "type": [ "object", "null" ], "description": "Retainer fee structure for this job, or null if the job is not a retained engagement." } ] }, "fee_events": { "type": "array", "items": { "$ref": "#/components/schemas/JobFeeEvent" }, "description": "All billing events for this job — placements plus retainer installments/milestones. Filter by the \"type\" field." }, "total_placement_fee": { "type": [ "number", "null" ], "description": "Sum of total_fee across all non-placeholder, non-cancelled placement events. Null when there are no such placements. This reflects the fees entered in the \"Fees and Placements\" section, unlike the top-level \"fee\" field which is a manually entered forecasting value on the job." } }, "required": [ "retainer", "fee_events", "total_placement_fee" ] }, "JobRetainer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Retainer UUID." }, "fee_type": { "type": "string", "description": "How the projected fee is calculated (\"percentage\", \"fixed\")." }, "fee_base": { "type": [ "string", "null" ], "description": "Basis the percentage applies to (e.g. \"first_year_salary\")." }, "fee_percentage": { "type": [ "number", "null" ], "description": "Fee percentage used when fee_type is percentage-based." }, "projected_fee": { "type": "number", "description": "Total projected engagement value for the retainer." }, "estimated_compensation": { "type": [ "number", "null" ], "description": "Estimated candidate compensation the fee is based on." }, "installment_count": { "type": "number", "description": "Number of installments the retainer is split into." }, "final_payment_type": { "type": "string", "description": "How the final payment is handled (e.g. \"on_placement\")." }, "currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code for the retainer." } }, "required": [ "id", "fee_type", "fee_base", "fee_percentage", "projected_fee", "estimated_compensation", "installment_count", "final_payment_type", "currency_code" ] }, "JobFeeEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Fee event UUID." }, "type": { "type": "string", "enum": [ "retainer", "milestone", "placement" ], "description": "Fee event type. \"placement\" is a completed placement fee; \"retainer\" and \"milestone\" are retained-search billing events." }, "label": { "type": [ "string", "null" ], "description": "Optional label for the fee event." }, "amount": { "type": [ "number", "null" ], "description": "Billable amount for this fee event. For placements, the full fee minus the retainers deducted from it: retainers billed on this job and, when the placement claimed one, a retainer pack retainer (see pack_retainer_amount). Never below 0. Null if unset." }, "total_fee": { "type": [ "number", "null" ], "description": "Full fee for the event (for placements, the commission base before splits). Null if unset." }, "currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code for the fee amounts (e.g. \"USD\"). Null if unset." }, "fee_type": { "type": [ "string", "null" ], "description": "How the fee is calculated (e.g. \"percentage\", \"fixed\")." }, "fee_percentage": { "type": [ "number", "null" ], "description": "Fee percentage used when fee_type is percentage-based." }, "compensation": { "type": [ "number", "null" ], "description": "Candidate compensation the fee percentage is applied to." }, "firm_commission_percent": { "type": [ "number", "null" ], "description": "Firm's commission percentage for this event (0–100)." }, "is_placeholder": { "type": "boolean", "description": "True if this is a projected/placeholder event rather than a confirmed one." }, "sequence": { "type": [ "number", "null" ], "description": "Ordering position within the fee schedule." }, "start_date": { "type": [ "string", "null" ], "description": "Start date (YYYY-MM-DD), if any." }, "expected_date": { "type": [ "string", "null" ], "description": "Expected billing/payment date (YYYY-MM-DD)." }, "actual_payment_date": { "type": [ "string", "null" ], "description": "Actual payment date (YYYY-MM-DD), once paid." }, "candidate_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Placed candidate UUID for placement events. Matches IDs from GET /v1/candidates/{id}." }, "offer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated job offer UUID, if any." }, "retainer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Parent retainer UUID for retainer installment events, if any." }, "fee_status_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Fee status UUID, if any." }, "fee_status_name": { "type": [ "string", "null" ], "description": "Fee status display name (e.g. \"Invoiced\", \"Paid\")." }, "fee_status_color": { "type": [ "string", "null" ], "description": "Hex color of the fee status badge." }, "fee_status_type": { "type": [ "string", "null" ], "enum": [ "pending", "invoiced", "paid", "cancelled" ], "description": "Underlying fee status category." }, "linked_retainer_pack_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Retainer pack UUID this placement is part of, from the client company's retainer packs. Null for other events and for placements outside any pack." }, "claimed_pack_retainer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the retainer pack retainer this placement used. Null when the placement claimed none, including extra hires linked to the pack at no retainer." }, "pack_retainer_amount": { "type": [ "number", "null" ], "description": "Amount of the claimed retainer pack retainer, deducted from this placement amount. Null when no pack retainer was claimed." } }, "required": [ "id", "type", "label", "amount", "total_fee", "currency_code", "fee_type", "fee_percentage", "compensation", "firm_commission_percent", "is_placeholder", "sequence", "start_date", "expected_date", "actual_payment_date", "candidate_id", "offer_id", "retainer_id", "fee_status_id", "fee_status_name", "fee_status_color", "fee_status_type", "linked_retainer_pack_id", "claimed_pack_retainer_id", "pack_retainer_amount" ] }, "JobStatusChange": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Status-change record UUID." }, "job_status_id": { "type": "string", "format": "uuid", "description": "Status the job entered. Matches ids from GET /v1/jobs/statuses." }, "job_status_name": { "type": [ "string", "null" ], "description": "Name of the status at the time it was recorded." }, "job_status_type": { "type": [ "string", "null" ], "enum": [ "not_started", "in_progress", "closed_won", "closed_lost" ], "description": "Lifecycle category of that status: not_started, in_progress, closed_won, or closed_lost." }, "entered_at": { "type": "string", "description": "ISO 8601 timestamp when the job entered this status." }, "exited_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the job left this status. Null while this is the current status." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when this history row was recorded." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "Team member who recorded the change. Null when the change was not attributed. Matches ids from GET /v1/team-members." }, "reason_text": { "type": [ "string", "null" ], "description": "Optional note stored with the status change." } }, "required": [ "id", "job_status_id", "job_status_name", "job_status_type", "entered_at", "exited_at", "created_at", "created_by", "reason_text" ] }, "CreateJobRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Job title (required). E.g. \"Senior Software Engineer\"." }, "company_name": { "type": "string", "description": "Client company name. At least one of company_name, company_domain, or company_linkedin_url required." }, "company_domain": { "type": "string", "description": "Client company website domain (e.g. \"acme.com\"). Used for matching or creating the company." }, "company_linkedin_url": { "type": "string", "format": "uri", "description": "Client company LinkedIn URL. Used for matching or creating the company." }, "pipeline_template_name": { "type": "string", "description": "Pipeline template name to use. Defaults to \"Default Template\" if omitted." }, "team_members": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID. Get from GET /v1/team-members. Falls back to team_member_email if not found." }, "team_member_email": { "type": "string", "description": "Team member email. Used when team_member_id is not provided or not found." }, "role_id": { "type": "string", "format": "uuid", "description": "Role UUID. Get from GET /v1/jobs/team-member-roles. Falls back to role_name if not found." }, "role_name": { "type": "string", "description": "Role name (e.g. \"Team Lead\"). Used when role_id is not provided or not found." } } }, "description": "Team members to assign with their roles." }, "job_description": { "type": "string", "description": "Plain-text job description. Returned as description in job detail, list, and search responses." }, "location": { "type": "string", "description": "Job location (e.g. \"San Francisco, CA\")." }, "primary_url": { "type": "string", "format": "uri", "description": "Primary job posting URL." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\", \"GBP\")." }, "job_function": { "type": "string", "description": "Department or function (e.g. \"Engineering\", \"Marketing\")." }, "open_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Job opening date (YYYY-MM-DD)." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Target close date (YYYY-MM-DD)." }, "salary_min": { "type": "integer", "minimum": 0, "description": "Minimum annual salary." }, "salary_max": { "type": "integer", "minimum": 0, "description": "Maximum annual salary." }, "salary_range": { "type": "string", "maxLength": 50, "description": "Salary range as a single number (\"120000\") or a dash-separated range (\"80000-120000\"). Parsed into the same structured range as salary_min/salary_max. Cannot be combined with salary_min or salary_max in the same request." }, "salary_details": { "type": "string", "maxLength": 500, "description": "Free-text salary details that complement the structured range (e.g. \"+ 0.5% equity, signing bonus negotiable\"). Max 500 characters." }, "fee": { "type": "number", "minimum": 0, "description": "Placement fee amount." }, "billing_contact_name": { "type": "string", "maxLength": 255, "description": "Name of the client-side billing contact for this job (max 255 characters)." }, "billing_contact_email": { "type": "string", "maxLength": 255, "format": "email", "description": "Email of the client-side billing contact for this job. Must be a valid email." }, "firm_commission_percent": { "type": "number", "minimum": 0, "maximum": 100, "description": "Firm commission percentage of the placement fee (0–100)." }, "deal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Deal UUIDs to link to this job on creation via the deal_jobs join table. Each deal must belong to the same team; otherwise the request is rejected with a validation error. Resolve IDs via POST /v1/deals/search. Max 50 deals per request." }, "client_contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Client contact UUIDs to assign to this job as client contacts. Each contact must already exist in your workspace, otherwise the request is rejected. Resolve IDs via GET /v1/client-contacts, or create contacts with POST /v1/client-contacts. Max 50 per request." }, "job_status_id": { "type": "string", "format": "uuid", "description": "Job status UUID to assign on creation. Get valid IDs from GET /v1/jobs/statuses. Defaults to the team default status when omitted." } }, "required": [ "title" ] }, "CreateJobResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobById" } }, "required": [ "success", "data" ] }, "JobById": { "allOf": [ { "$ref": "#/components/schemas/JobBase" }, { "type": "object", "properties": { "share_links": { "type": "array", "items": { "$ref": "#/components/schemas/JobShareLink" }, "default": [], "description": "Active client-pipeline share links for this job (always included in detail view). Expired closed-job links are omitted." }, "linked_deals": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedJobDeal" }, "description": "CRM deals linked to this job via the deal_jobs join table (separate from the Fees and Placements section). Omitted for API-key callers without deals:read." }, "fees": { "allOf": [ { "$ref": "#/components/schemas/JobFees" }, { "description": "Fee and placement data from the \"Fees and Placements\" section (retainer structure, billing events, and total placement fee). Omitted for API-key callers without compensation:read." } ] }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "default": [], "description": "Custom attribute values (always included in detail view). Definitions from GET /v1/custom-fields/jobs." }, "pipeline_stages": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" }, "description": "This job's own pipeline stages ordered by stage_order, archived ones included. Use stage IDs for filtering candidates or moving them between stages." }, "referral_partners": { "type": "array", "items": { "$ref": "#/components/schemas/JobReferralPartner" }, "description": "Client contacts who referred this job, oldest first. Manage them with /v1/jobs/{id}/referral-partners. Omitted for API-key callers without fees:read." }, "pack_retainer_split": { "type": "array", "items": { "$ref": "#/components/schemas/JobPackRetainerSplitRow" }, "description": "Credit split copied onto a retainer pack retainer when a placement on this job claims it. Empty when the job has none (claimed retainers then keep the pack default split). Set it with PUT /v1/jobs/{id}/pack-retainer-split. Omitted for API-key callers without fees:read." } }, "required": [ "pipeline_stages" ] } ] }, "PipelineStage": { "type": "object", "properties": { "id": { "type": "string", "description": "Pipeline stage UUID, the same on every job and in GET /v1/jobs/pipeline-stages. Use in pipeline_stage_ids_included/excluded filters in POST /v1/persons/search, or as stage_id in POST /v1/candidates/update-stage." }, "name": { "type": "string", "description": "Stage display name (e.g. \"Application Review\", \"Technical Interview\")." }, "stage_order": { "type": "number", "description": "Sort key for this job's stages. Sort ascending to get the pipeline order. Values can be negative or decimal and are not consecutive, so use them only for sorting." }, "is_archived": { "type": "boolean", "description": "True if the stage is archived on this job or was deleted from the team's stages. Candidates already in it stay there, but POST /v1/candidates/update-stage rejects moving anyone into it (400 STAGE_ARCHIVED)." }, "is_rejection_stage": { "type": "boolean", "description": "True if this stage represents rejection/disqualification." }, "is_interviewing_stage": { "type": "boolean", "description": "True if this stage represents an interview round." }, "is_offer_stage": { "type": "boolean", "description": "True if this stage represents an offer." }, "is_placement_stage": { "type": "boolean", "description": "True if this stage represents a placement (candidate hired)." }, "job_pipeline_stage_id": { "type": "string", "description": "This job's copy of the stage. Matches current_job_pipeline_stage_id in candidate webhooks and previous_stage_id / new_stage_id in POST /v1/candidates/update-stage responses." } }, "required": [ "id", "name", "stage_order", "is_archived", "is_rejection_stage", "is_interviewing_stage", "is_offer_stage", "is_placement_stage", "job_pipeline_stage_id" ] }, "JobReferralPartner": { "type": "object", "properties": { "client_contact_id": { "type": "string", "format": "uuid", "description": "Client contact UUID of the referral partner. Matches IDs from GET /v1/client-contacts." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Person UUID behind the client contact. Use GET /v1/persons/{id} for contact details." }, "name": { "type": [ "string", "null" ], "description": "Partner's full name." }, "title": { "type": [ "string", "null" ], "description": "Partner's current job title." }, "image_url": { "type": [ "string", "null" ], "description": "Profile image URL." }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the client company the contact belongs to." }, "company_name": { "type": [ "string", "null" ], "description": "Name of the client company the contact belongs to." }, "default_split_percentage": { "type": [ "number", "null" ], "description": "Default percentage offered to this partner when a placement is logged on the job. More than 0 and at most 100, rounded to 2 decimals. Null when no default is set." }, "default_mode": { "type": "string", "enum": [ "off_the_top", "team_pool" ], "description": "How the referral partner is paid on a placement. `off_the_top`: the percentage is taken from the full placement fee before the team is credited. `team_pool`: the partner shares the team commission pool with the team members." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the partner was added to the job." } }, "required": [ "client_contact_id", "person_id", "name", "title", "image_url", "company_id", "company_name", "default_split_percentage", "default_mode", "created_at" ] }, "JobPackRetainerSplitRow": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID credited. Matches IDs from GET /v1/team-members." }, "team_member_name": { "type": [ "string", "null" ], "description": "Team member's full name. Null when no name is set." }, "role": { "type": [ "string", "null" ], "description": "Optional label for why this person gets credit (e.g. \"Sales\")." }, "split_percentage": { "type": "number", "description": "Share of the retainer credited to this team member (0-100). All rows total 100." } }, "required": [ "team_member_id", "team_member_name", "role", "split_percentage" ] }, "JobsSearchBody": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200, "description": "Max records to return (1–200). Defaults to 200." }, "sort_by": { "type": "string", "description": "Sort column. Values: title, company, status, fee, created_at, days_since_opened, location, total_candidates, or custom_. Defaults to created_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Full-text search across job title, description, location, and company name/domain." }, "location_keywords": { "type": "array", "items": { "type": "string" }, "description": "Search specifically in the job location field." }, "vector_search": { "type": "string", "minLength": 5, "description": "AI semantic search query (min 5 chars). Uses vector embeddings for contextual matching." }, "is_archived": { "type": "boolean", "description": "Filter by archive status. Omit to include both active and archived jobs (recommended for similar past searches, comps, pitch prep, and company/sector history). Pass false for active jobs only (current pipeline / open searches). Pass true for archived jobs only." }, "job_status_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only jobs with these status IDs. Status IDs are returned in job list/detail responses as job_status_id." }, "job_status_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude jobs with these status IDs." }, "company_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only jobs for these client companies. Get IDs from GET /v1/companies." }, "company_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude jobs for these client companies." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter to jobs owned by these team members (owner role). Get IDs from GET /v1/team-members." }, "team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter to jobs with any of these team members assigned. Get IDs from GET /v1/team-members." }, "team_member_role_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter to jobs that have members with these roles. Get role IDs from GET /v1/jobs/team-member-roles." }, "is_public": { "type": "boolean", "description": "Filter for publicly posted jobs only." }, "created_at_gte": { "type": "string", "format": "date-time", "description": "Filter jobs created on or after this ISO 8601 datetime (e.g. \"2024-01-01T00:00:00Z\")." }, "created_at_lte": { "type": "string", "format": "date-time", "description": "Filter jobs created on or before this ISO 8601 datetime (e.g. \"2024-12-31T23:59:59Z\")." }, "updated_at_gte": { "type": "string", "format": "date-time", "description": "Filter jobs updated on or after this ISO 8601 datetime (e.g. \"2024-01-01T00:00:00Z\")." }, "updated_at_lte": { "type": "string", "format": "date-time", "description": "Filter jobs updated on or before this ISO 8601 datetime (e.g. \"2024-12-31T23:59:59Z\")." }, "list_id": { "type": "string", "format": "uuid", "description": "Filter to jobs in this saved list." }, "select_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions." }, "excluded_values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/jobs." }, "numeric_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}." }, "min": { "type": [ "number", "null" ], "description": "Minimum value (inclusive). Null for no lower bound." }, "max": { "type": [ "number", "null" ], "description": "Maximum value (inclusive). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/jobs." }, "date_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}." }, "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/jobs." }, "team_member_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to include. Get IDs from GET /v1/team-members." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified team members (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no team member assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/jobs, team member IDs from GET /v1/team-members." }, "company_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-company type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to include. Get IDs from GET /v1/companies/search or search-companies." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified companies (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no company assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by multi-company custom fields. Get attribute_id from GET /v1/custom-fields/jobs." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "linked_deals", "fees", "client_contacts", "share_links", "pipeline_stages", "job_status_changes" ] }, "description": "Extra sections to embed. Values: custom_fields, linked_deals, fees, client_contacts, share_links, pipeline_stages, job_status_changes. Omit for base fields only. job_status_changes embeds the recorded status history, oldest first. For API-key callers, linked_deals requires deals:read and fees requires compensation:read; inaccessible sections are omitted." } } }, "JobsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/JobBase" }, { "type": "object", "properties": { "pipeline_stages": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" }, "description": "Ordered pipeline stages for this job, same as GET /v1/jobs/{id}. Included when include contains \"pipeline_stages\"." } } } ] } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobById" } }, "required": [ "success", "data" ] }, "UpdateJobRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "New job title." }, "job_description": { "type": "string", "description": "Plain-text job description. Replaces the existing description returned by job detail, list, and search responses." }, "location": { "type": [ "string", "null" ], "description": "Job location (e.g. \"San Francisco, CA\"). Pass null to clear." }, "job_status_id": { "type": "string", "format": "uuid", "description": "Job status UUID. Get valid IDs from GET /v1/jobs/statuses." }, "currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code (e.g. \"USD\")." }, "salary_min": { "type": [ "integer", "null" ], "minimum": 0, "description": "Minimum annual salary. Pass null to clear the salary range." }, "salary_max": { "type": [ "integer", "null" ], "minimum": 0, "description": "Maximum annual salary. Pass null to clear the salary range." }, "salary_range": { "type": [ "string", "null" ], "maxLength": 50, "description": "Salary range as a single number (\"120000\") or a dash-separated range (\"80000-120000\"). Parsed into the same structured range as salary_min/salary_max. Pass null to clear. Cannot be combined with salary_min or salary_max in the same request." }, "salary_details": { "type": [ "string", "null" ], "maxLength": 500, "description": "Free-text salary details that complement the structured range (e.g. \"+ 0.5% equity\"). Max 500 characters. Pass null to clear." }, "billing_contact_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Name of the client-side billing contact (max 255 characters). Pass null to clear." }, "billing_contact_email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email", "description": "Email of the client-side billing contact. Must be a valid email. Pass null to clear." }, "deal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Deal UUIDs to link to this job. Replaces ALL existing links in the deal_jobs join table. Pass an empty array to remove every linked deal. Omit the field to leave links unchanged. Max 50 deals per request." }, "client_contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Client contact UUIDs to assign to this job. Replaces ALL contacts currently on the job. Pass an empty array to remove every contact, or omit the field to leave them unchanged. Max 50 per request." }, "fee": { "type": [ "number", "null" ], "minimum": 0, "description": "Placement fee amount. Pass null to clear." }, "firm_commission_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Firm commission percentage (0–100)." }, "primary_url": { "type": [ "string", "null" ], "format": "uri", "description": "Primary job posting URL. Pass null to clear." }, "job_function": { "type": [ "string", "null" ], "description": "Department/function (e.g. \"Engineering\"). Pass null to clear." }, "open_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Job opening date (YYYY-MM-DD)." }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Target close date (YYYY-MM-DD)." }, "is_archived": { "type": "boolean", "description": "Set true to archive the job, false to unarchive." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/jobs." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/jobs." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all existing values for this multi-select, multi-team-member, or multi-company attribute." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to update. Get attribute definitions from GET /v1/custom-fields/jobs. For select fields, pass the tag NAME or the tag option UUID returned in that definition." } }, "additionalProperties": false }, "UpdateJobResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message." } }, "required": [ "message" ] } }, "required": [ "success", "data" ] }, "JobCandidatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobCandidate" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobCandidate": { "type": "object", "properties": { "id": { "type": "string", "description": "Candidate UUID. Use in GET /v1/candidates/{id} for full stage history." }, "person_id": { "type": "string", "description": "Associated person UUID. Use in GET /v1/persons/{id} for full profile." }, "name": { "type": [ "string", "null" ], "description": "Candidate full name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title from their person profile." }, "current_company_name": { "type": [ "string", "null" ], "description": "Current employer name." }, "current_company_id": { "type": [ "string", "null" ], "description": "Current employer company UUID." }, "current_pipeline_stage_name": { "type": [ "string", "null" ], "description": "Name of the current pipeline stage in this job." }, "current_pipeline_stage_id": { "type": [ "string", "null" ], "description": "UUID of the current pipeline stage." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when candidate was added to this job." }, "sourced_by": { "type": [ "string", "null" ], "description": "UUID of the team member who sourced this candidate. Matches IDs from GET /v1/team-members." }, "owner_id": { "type": [ "string", "null" ], "description": "UUID of the team member who owns this candidate. Matches IDs from GET /v1/team-members." } }, "required": [ "id", "person_id", "name", "current_job_title", "current_company_name", "current_company_id", "current_pipeline_stage_name", "current_pipeline_stage_id", "created_at", "sourced_by", "owner_id" ] }, "JobApplicantsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobApplicant" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobApplicant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Applicant UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID this application belongs to." }, "job_posting_id": { "type": "string", "format": "uuid", "description": "Public job posting UUID the application was submitted against." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked person UUID after the applicant is added to the job pipeline (`selected`). Null for unprocessed or rejected applicants." }, "name": { "type": "string", "description": "Applicant full name." }, "email": { "type": "string", "description": "Applicant email address." }, "status": { "type": "string", "enum": [ "new", "selected", "not_a_fit" ], "description": "Applicant review status. `new` is unprocessed (still on the Applicants tab), `selected` was added to the job pipeline, and `not_a_fit` was rejected from the Applicants tab." }, "linkedin_profile_url": { "type": [ "string", "null" ], "description": "LinkedIn profile URL from the application form, if collected." }, "portfolio_url": { "type": [ "string", "null" ], "description": "Portfolio URL from the application form, if collected." }, "additional_information": { "type": [ "string", "null" ], "description": "Free-text additional information from the application form, if collected." }, "resume_url": { "type": [ "string", "null" ], "description": "Signed download URL for the uploaded resume. Null when no resume was submitted. Re-fetch when expired." }, "cover_letter_url": { "type": [ "string", "null" ], "description": "Signed download URL for the uploaded cover letter. Null when no cover letter was submitted. Re-fetch when expired." }, "not_a_fit_note": { "type": [ "string", "null" ], "description": "Plain-text recruiter note recorded when marking the applicant as not a fit. Null otherwise." }, "fields_response": { "type": "object", "properties": { "fields": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "text", "email", "phone", "textarea", "url" ] }, "value": { "type": "string" } }, "required": [ "field_id", "type", "value" ] }, { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "number" ] }, "value": { "type": "number" } }, "required": [ "field_id", "type", "value" ] }, { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "date" ] }, "value": { "type": "string" } }, "required": [ "field_id", "type", "value" ] }, { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "select" ] }, "value": { "type": "string" } }, "required": [ "field_id", "type", "value" ] }, { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "multi_select" ] }, "value": { "type": "array", "items": { "type": "string" } } }, "required": [ "field_id", "type", "value" ] }, { "type": "object", "properties": { "field_id": { "type": "string", "description": "Application form field ID." }, "type": { "type": "string", "enum": [ "file" ] }, "value": { "type": "object", "properties": { "name": { "type": "string", "description": "Original uploaded filename." }, "size": { "type": "number", "description": "File size in bytes." }, "type": { "type": "string", "description": "MIME type of the uploaded file." }, "url": { "type": "string", "description": "Short-lived signed download URL. Re-fetch this endpoint when the URL expires (about 15 minutes). Empty string if the file could not be signed." } }, "required": [ "name", "size", "type", "url" ] } }, "required": [ "field_id", "type", "value" ] } ] } } }, "required": [ "fields" ], "description": "Submitted application form answers. File fields include a signed download URL instead of a storage path." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the application was submitted." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the applicant record was last updated." } }, "required": [ "id", "job_id", "job_posting_id", "person_id", "name", "email", "status", "linkedin_profile_url", "portfolio_url", "additional_information", "resume_url", "cover_letter_url", "not_a_fit_note", "fields_response", "created_at", "updated_at" ] }, "JobDocumentTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobDocumentType" } } }, "required": [ "success", "data" ] }, "JobDocumentType": { "type": "object", "properties": { "type": { "type": "string", "description": "Document type key." }, "name": { "type": "string", "description": "Document type display name." } }, "required": [ "type", "name" ] }, "JobDocumentsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobDocument" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobDocument": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document was uploaded." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document was last updated." }, "type": { "type": "string", "description": "Team-defined document type key." }, "title": { "type": [ "string", "null" ], "description": "Document title or filename." }, "link": { "type": "string", "description": "Document link. Stored-file links are short-lived and should be re-fetched after they expire." }, "text_content": { "type": [ "string", "null" ], "description": "Extracted plain-text document content. Included only when include_text=true and text is available." }, "char_count": { "type": "number", "description": "Number of characters returned in text_content. Included only when include_text=true." }, "truncated": { "type": "boolean", "description": "Whether text_content was truncated due to response size limits. Included only when include_text=true." } }, "required": [ "created_at", "updated_at", "type", "title", "link" ] }, "JobDocumentUploadMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload. Allowed types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB." }, "title": { "type": "string", "description": "Document title. Defaults to the original filename if omitted." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values: job_description, offer_letter, contract, legal_document, other. Teams may add custom values." } }, "required": [ "file", "type" ] }, "JobDocumentUploadRequest": { "type": "object", "properties": { "file_url": { "type": "string", "format": "uri", "description": "Publicly accessible HTTPS URL of the file to download and attach to the job. The file must be 25 MB or smaller." }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Document title or filename. Defaults to the downloaded filename." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values: job_description, offer_letter, contract, legal_document, other. Teams may add custom values." } }, "required": [ "file_url", "type" ] }, "JobDocumentUploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created document UUID." }, "created_at": { "type": "string", "description": "ISO 8601 upload timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." }, "type": { "type": "string", "description": "Team-defined document type key." }, "title": { "type": [ "string", "null" ], "description": "Document title or filename." }, "link": { "type": "string", "description": "Short-lived signed download URL. Re-fetch the document after this link expires." } }, "required": [ "id", "created_at", "updated_at", "type", "title", "link" ] } }, "required": [ "success", "data" ] }, "JobTargetCompaniesMutationRequest": { "type": "object", "properties": { "company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Company UUIDs to add to or remove from the job target company list. Resolve names with POST /v1/companies/search first." } }, "required": [ "company_ids" ] }, "JobTargetCompaniesAddResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobTargetCompaniesAddResult" } }, "required": [ "success", "data" ] }, "JobTargetCompaniesAddResult": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "added_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs newly added to the job target company list." }, "already_present_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs that were already on the job target company list." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/JobTargetCompanyMutationFailure" }, "description": "Company UUIDs that could not be added. Other valid IDs in the same request are still processed." } }, "required": [ "job_id", "added_ids", "already_present_ids", "failed" ] }, "JobTargetCompanyMutationFailure": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Company UUID that could not be processed." }, "reason": { "type": "string", "description": "Reason this company could not be processed, such as not_found." } }, "required": [ "id", "reason" ] }, "JobTargetCompaniesRemoveResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobTargetCompaniesRemoveResult" } }, "required": [ "success", "data" ] }, "JobTargetCompaniesRemoveResult": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "removed_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs removed from the job target company list." }, "not_found_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Valid company UUIDs that were not on the job target company list at removal time." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/JobTargetCompanyMutationFailure" }, "description": "Company UUIDs that could not be removed. Other valid IDs in the same request are still processed." } }, "required": [ "job_id", "removed_ids", "not_found_ids", "failed" ] }, "JobTeamMemberRolesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobTeamMemberRole" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobTeamMemberRole": { "type": "object", "properties": { "id": { "type": "string", "description": "Role UUID. Use in team_member_role_ids filters in POST /v1/jobs/search or POST /v1/persons/search." }, "name": { "type": "string", "description": "Role display name (e.g. \"Team Lead\", \"Executive Sponsor\")." }, "is_owner_role": { "type": "boolean", "description": "True if this is the primary owner/lead role." }, "position": { "type": "number", "description": "Display sort order (ascending)." } }, "required": [ "id", "name", "is_owner_role", "position" ] }, "JobPackRetainerSplitResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobPackRetainerSplit" } }, "required": [ "success", "data" ] }, "JobPackRetainerSplit": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "splits": { "type": "array", "items": { "$ref": "#/components/schemas/JobPackRetainerSplitRow" }, "description": "Credit split copied onto a retainer pack retainer when a placement on this job claims it. Empty means claimed retainers keep the pack default split." } }, "required": [ "job_id", "splits" ] }, "ReplaceJobPackRetainerSplitRequest": { "type": "object", "properties": { "splits": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to credit. Get IDs from GET /v1/team-members." }, "role": { "type": [ "string", "null" ], "maxLength": 100, "description": "Optional label for why this person gets credit (e.g. \"Sales\")." }, "split_percentage": { "type": "number", "description": "Share of the retainer for this team member: more than 0 and at most 100." } }, "required": [ "team_member_id", "split_percentage" ] }, "maxItems": 100, "description": "The job's full pack retainer split, replacing the current one. Percentages must total 100. Send an empty list to remove it, so claimed retainers use the pack default split. Retainers already claimed keep the split they were given." } }, "required": [ "splits" ] }, "JobReferralPartnersListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobReferralPartner" } } }, "required": [ "success", "data" ] }, "AddJobReferralPartnerRequest": { "type": "object", "properties": { "client_contact_id": { "type": "string", "format": "uuid", "description": "Client contact UUID to add as a referral partner. Any live client contact in your workspace can be added, from any company. Find IDs with GET /v1/client-contacts?keywords=..." }, "default_split_percentage": { "type": [ "number", "null" ], "description": "Default percentage offered to this partner when a placement is logged on the job. More than 0 and at most 100, rounded to 2 decimals. Null when no default is set." }, "default_mode": { "type": "string", "enum": [ "off_the_top", "team_pool" ], "description": "How the partner is paid on placements by default. Defaults to `off_the_top`." } }, "required": [ "client_contact_id" ] }, "JobReferralPartnerResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/JobReferralPartner" } }, "required": [ "success", "data" ] }, "UpdateJobReferralPartnerRequest": { "type": "object", "properties": { "default_split_percentage": { "type": [ "number", "null" ], "description": "New default percentage, or null to clear it. Omit to leave it unchanged." }, "default_mode": { "type": "string", "enum": [ "off_the_top", "team_pool" ], "description": "New default payment mode. Omit to leave it unchanged." } } }, "JobStatusesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobStatus" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "JobStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Job status UUID." }, "name": { "type": "string", "description": "Status name (e.g. \"Active\", \"Filled\")." }, "color": { "type": [ "string", "null" ], "description": "Display color." }, "stage_order": { "type": "number", "description": "Display sort order (ascending)." }, "is_default_status": { "type": "boolean", "description": "True if this is the default status." }, "status_type": { "type": "string", "enum": [ "not_started", "in_progress", "closed_won", "closed_lost" ], "description": "Lifecycle category used for reporting and open/closed behavior: not_started, in_progress, closed_won, or closed_lost. Independent of the custom status name." } }, "required": [ "id", "name", "color", "stage_order", "is_default_status", "status_type" ] }, "PipelineStagesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamPipelineStage" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "TeamPipelineStage": { "type": "object", "properties": { "id": { "type": "string", "description": "Pipeline stage UUID, the same on every job and in GET /v1/jobs/pipeline-stages. Use in pipeline_stage_ids_included/excluded filters in POST /v1/persons/search, or as stage_id in POST /v1/candidates/update-stage." }, "name": { "type": "string", "description": "Stage display name (e.g. \"Application Review\", \"Technical Interview\")." }, "stage_order": { "type": "number", "description": "Team-wide sort value for listing stages. It is not the order of any job's pipeline and can be 0 or repeat; for a job's order use pipeline_stages on GET /v1/jobs/{id}." }, "is_archived": { "type": "boolean", "description": "True if the stage was deleted from the team's stages. Deleted stages are returned only with include_deleted=true. Candidates can't be moved into them." }, "is_rejection_stage": { "type": "boolean", "description": "True if this stage represents rejection/disqualification." }, "is_interviewing_stage": { "type": "boolean", "description": "True if this stage represents an interview round." }, "is_offer_stage": { "type": "boolean", "description": "True if this stage represents an offer." }, "is_placement_stage": { "type": "boolean", "description": "True if this stage represents a placement (candidate hired)." } }, "required": [ "id", "name", "stage_order", "is_archived", "is_rejection_stage", "is_interviewing_stage", "is_offer_stage", "is_placement_stage" ] }, "ListsSearchBody": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records to return (1–100). Defaults to 100." }, "sort_by": { "type": "string", "enum": [ "name", "created_at", "updated_at", "item_count" ], "default": "created_at", "description": "Column to sort by. Accepted values: name, created_at, updated_at, item_count. Defaults to created_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "keywords": { "type": "string", "description": "Search keyword to filter lists by name. Case-insensitive partial match." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "Filter by list type: \"persons\" or \"companies\". Omit to return all types." }, "is_archived": { "type": "boolean", "default": false, "description": "When true, return archived lists only. When false (default), return non-archived lists." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter to lists owned by these team member UUIDs." }, "is_public": { "type": "boolean", "description": "Filter by public/private visibility. Omit to return both." } } }, "ListsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "List": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique list UUID." }, "name": { "type": "string", "description": "List name." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "Type of entities in this list: \"persons\" or \"companies\"." }, "is_public": { "type": "boolean", "description": "Whether the list is visible to all team members." }, "is_archived": { "type": "boolean", "description": "Whether the list has been archived." }, "linked_job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this list is linked to, if any." }, "linked_person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Person UUID this list is linked to, if any." }, "linked_organization_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company UUID this list is linked to, if any." }, "item_count": { "type": "number", "description": "Number of non-deleted items in the list." }, "created_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "Creator first name." }, "last_name": { "type": [ "string", "null" ], "description": "Creator last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who created the list." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." } }, "required": [ "id", "first_name", "last_name" ] }, "description": "List owners." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 last-updated timestamp." } }, "required": [ "id", "name", "list_type", "is_public", "is_archived", "linked_job_id", "linked_person_id", "linked_organization_company_id", "item_count", "created_by", "owners", "created_at", "updated_at" ] }, "ListByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ListDetail" } }, "required": [ "success", "data" ] }, "ListDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique list UUID." }, "name": { "type": "string", "description": "List name." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "Type of entities in this list: \"persons\" or \"companies\"." }, "is_public": { "type": "boolean", "description": "Whether the list is visible to all team members." }, "is_archived": { "type": "boolean", "description": "Whether the list has been archived." }, "linked_job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this list is linked to, if any." }, "linked_person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Person UUID this list is linked to, if any." }, "linked_organization_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company UUID this list is linked to, if any." }, "item_count": { "type": "number", "description": "Number of non-deleted items in the list." }, "created_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "Creator first name." }, "last_name": { "type": [ "string", "null" ], "description": "Creator last name." } }, "required": [ "id", "first_name", "last_name" ], "description": "Team member who created the list." }, "owners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "first_name": { "type": [ "string", "null" ], "description": "Team member first name." }, "last_name": { "type": [ "string", "null" ], "description": "Team member last name." } }, "required": [ "id", "first_name", "last_name" ] }, "description": "List owners." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 last-updated timestamp." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" }, "description": "Paginated list items." }, "items_total": { "type": "number", "description": "Total number of non-deleted items in the list." } }, "required": [ "id", "name", "list_type", "is_public", "is_archived", "linked_job_id", "linked_person_id", "linked_organization_company_id", "item_count", "created_by", "owners", "created_at", "updated_at", "items", "items_total" ] }, "ListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "List item UUID." }, "person": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Person UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "linkedin_url": { "type": [ "string", "null" ], "description": "Person LinkedIn URL." } }, "required": [ "id", "first_name", "last_name", "linkedin_url" ], "description": "Person data when list_type is \"persons\". Null for company lists." }, "company": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Company UUID." }, "name": { "type": [ "string", "null" ], "description": "Company name." } }, "required": [ "id", "name" ], "description": "Company data when list_type is \"companies\". Null for person lists." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the item was added." } }, "required": [ "id", "person", "company", "created_at" ] }, "ListCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "List name (required)." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "default": "persons", "description": "Type of entities in this list. Defaults to \"persons\"." }, "is_public": { "type": "boolean", "default": false, "description": "Whether the list is visible to all team members. Defaults to false." }, "linked_job_id": { "type": "string", "format": "uuid", "description": "Job UUID to link this list to." }, "linked_person_id": { "type": "string", "format": "uuid", "description": "Person UUID to link this list to." }, "linked_organization_company_id": { "type": "string", "format": "uuid", "description": "Company UUID to link this list to." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to assign as list owners. If omitted, the caller is auto-assigned." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to attribute as the list creator. Required for API-key auth (which has no implicit user context). Ignored when using session or OAuth auth." } }, "required": [ "name" ] }, "ListCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ListCreateResponseData" } }, "required": [ "success", "data" ] }, "ListCreateResponseData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Created list UUID." }, "name": { "type": "string", "description": "List name." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "List type." }, "is_public": { "type": "boolean", "description": "Public visibility." }, "is_archived": { "type": "boolean", "description": "Archived status." }, "linked_job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked job UUID." }, "linked_person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked person UUID." }, "linked_organization_company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked company UUID." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 creation timestamp." } }, "required": [ "id", "name", "list_type", "is_public", "is_archived", "linked_job_id", "linked_person_id", "linked_organization_company_id", "created_at" ] }, "ListItemsMutationRequest": { "type": "object", "properties": { "person_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Person UUIDs to add or remove. Only valid for lists with list_type \"persons\"." }, "company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add or remove. Only valid for lists with list_type \"companies\"." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to attribute as the actor for this mutation. Required for API-key auth (which has no implicit user context). Ignored when using session or OAuth auth." } } }, "ListItemsAddResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "list_id": { "type": "string", "format": "uuid", "description": "List UUID." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "Type of entities accepted by this list." }, "added_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs inserted as new list items." }, "reactivated_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs whose previously removed list item was restored." }, "already_present_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs that were already active in the list." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Person or company UUID." }, "reason": { "type": "string", "description": "Why this ID was not processed, such as not_found or wrong_list_type." } }, "required": [ "id", "reason" ] }, "description": "IDs that could not be added. Other valid IDs in the same request are still processed." } }, "required": [ "list_id", "list_type", "added_ids", "reactivated_ids", "already_present_ids", "failed" ] } }, "required": [ "success", "data" ] }, "ListItemsRemoveResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "list_id": { "type": "string", "format": "uuid", "description": "List UUID." }, "list_type": { "type": "string", "enum": [ "persons", "companies" ], "description": "Type of entities accepted by this list." }, "removed_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs soft-removed from the list." }, "not_found_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Valid IDs that were not active members of the list at removal time." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Person or company UUID." }, "reason": { "type": "string", "description": "Why this ID was not processed, such as not_found or wrong_list_type." } }, "required": [ "id", "reason" ] }, "description": "IDs that could not be removed. Other valid IDs in the same request are still processed." } }, "required": [ "list_id", "list_type", "removed_ids", "not_found_ids", "failed" ] } }, "required": [ "success", "data" ] }, "MeetingRecordingsListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingRecordingListItem" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "MeetingRecordingListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Meeting recording UUID." }, "calendar_meeting_id": { "type": [ "string", "null" ], "description": "Associated calendar meeting UUID." }, "calendar_meeting": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Calendar meeting UUID." }, "meeting_title": { "type": [ "string", "null" ], "description": "Meeting title." }, "meeting_url": { "type": "string", "description": "Meeting URL (e.g. Zoom/Google Meet link)." }, "start_time": { "type": "string", "description": "Meeting start time (ISO 8601)." } }, "required": [ "id", "meeting_title", "meeting_url", "start_time" ], "description": "Calendar meeting details." }, "meeting_started_at": { "type": [ "string", "null" ], "description": "When the meeting started (ISO 8601)." }, "meeting_ended_at": { "type": [ "string", "null" ], "description": "When the meeting ended (ISO 8601)." }, "recording_duration_seconds": { "type": [ "number", "null" ], "description": "Duration of the recording in seconds." }, "processing_status": { "type": [ "string", "null" ], "description": "Processing status: pending, processing, completed, or failed." }, "has_transcript": { "type": "boolean", "description": "Whether a transcript is available. Use GET /v1/meeting-recordings/{id} to fetch the full transcript." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "calendar_meeting_id", "calendar_meeting", "meeting_started_at", "meeting_ended_at", "recording_duration_seconds", "processing_status", "has_transcript", "created_at", "updated_at" ] }, "MeetingRecordingByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MeetingRecordingDetail" } }, "required": [ "success", "data" ] }, "MeetingRecordingDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Meeting recording UUID." }, "calendar_meeting_id": { "type": [ "string", "null" ], "description": "Associated calendar meeting UUID." }, "calendar_meeting": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Calendar meeting UUID." }, "meeting_title": { "type": [ "string", "null" ], "description": "Meeting title." }, "meeting_url": { "type": "string", "description": "Meeting URL (e.g. Zoom/Google Meet link)." }, "start_time": { "type": "string", "description": "Meeting start time (ISO 8601)." } }, "required": [ "id", "meeting_title", "meeting_url", "start_time" ], "description": "Calendar meeting details (always included when available)." }, "meeting_started_at": { "type": [ "string", "null" ], "description": "When the meeting started (ISO 8601)." }, "meeting_ended_at": { "type": [ "string", "null" ], "description": "When the meeting ended (ISO 8601)." }, "recording_duration_seconds": { "type": [ "number", "null" ], "description": "Duration of the recording in seconds." }, "processing_status": { "type": [ "string", "null" ], "description": "Processing status: pending, processing, completed, or failed." }, "transcript_text": { "type": [ "string", "null" ], "description": "Full transcript text. Null when no transcript is available (e.g. recording still processing)." }, "summary_text": { "type": [ "string", "null" ], "description": "Plain-text AI-generated summary of the meeting. Null when no summary has been generated yet. Prefer this over `transcript_text` for high-level recap." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "calendar_meeting_id", "calendar_meeting", "meeting_started_at", "meeting_ended_at", "recording_duration_seconds", "processing_status", "transcript_text", "summary_text", "created_at", "updated_at" ] }, "PersonActivityTypesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonActivityTypeItem" } } }, "required": [ "success", "data" ] }, "PersonActivityTypeItem": { "type": "object", "properties": { "type": { "type": "string", "description": "Activity type key. Use this value as `activity_type` when creating activities or as a member of `activity_types` / `excluded_activity_types` when listing them." }, "name": { "type": "string", "description": "Human-readable label for the activity type." }, "protected": { "type": "boolean", "description": "True when the type is a built-in system type that cannot be deleted." }, "counts_as_engagement": { "type": "boolean", "description": "True when activities of this type advance the contact’s last-engaged timestamp." }, "is_archived": { "type": "boolean", "description": "True when the type has been hidden from the UI; archived types are excluded by default." }, "system_generated": { "type": "boolean", "description": "True when activities of this type are created by an integration and cannot be created, updated, or deleted via the API." } }, "required": [ "type", "name", "protected", "counts_as_engagement", "is_archived", "system_generated" ] }, "AddPersonActivityRequest": { "type": "object", "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL to identify the person." }, "email": { "type": "string", "format": "email", "description": "Email address to identify the person." }, "full_name": { "type": "string", "description": "Full name to identify the person. Least precise — prefer linkedin_url, email, or person_id." }, "person_id": { "type": "string", "format": "uuid", "description": "Person UUID (most precise). Get from POST /v1/persons/search or GET /v1/persons/{id}." }, "activity_type": { "type": "string", "minLength": 1, "description": "Activity type key. Standard values: secondary_note (general note), meeting_note, meeting_transcript, email, interview_note, linkedin_message, text_message, candidate_summary, linkedin_message_response, call_note. Teams can also define custom activity types from Settings → Activity Types; discover the full list (including custom types) with GET /v1/person-activities/types." }, "activity_content": { "type": "string", "description": "Activity body text. Stored as both HTML and plain text." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to record as the activity creator. Ignored for session and OAuth callers (the authenticated member is always recorded). Required for API-key auth, which has no implicit member context." }, "job_id": { "type": "string", "format": "uuid", "description": "Optional job UUID to associate this activity with a specific search. When provided, the identified person must already have a candidate record on that job — otherwise the request returns a 400 error. Resolve job IDs with POST /v1/jobs/search." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for when the event actually occurred (e.g. \"2024-01-10T14:00:00Z\"). This is distinct from `created_at`, which is a system-managed timestamp for when the activity record was written and cannot be set by the caller. Use `occurred_at` to backdate or record the real event time (for example, a meeting that happened last week). If omitted, it defaults to `created_at`." } }, "required": [ "activity_type", "activity_content" ] }, "AddPersonActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AddPersonActivityResponseData" } }, "required": [ "success", "data" ] }, "AddPersonActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "description": "Created activity UUID. Use in GET /v1/person-activities/{id} to retrieve." }, "person_id": { "type": "string", "description": "Person UUID the activity was attached to." }, "activity_type": { "type": "string", "description": "Activity type that was created." } }, "required": [ "id", "person_id", "activity_type" ] }, "GetPersonActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/GetPersonActivityResponseData" } }, "required": [ "success", "data" ] }, "GetPersonActivityResponseData": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity UUID." }, "person_id": { "type": "string", "description": "Person UUID this activity belongs to." }, "activity_type": { "type": "string", "description": "Activity type key." }, "activity_content": { "type": "string", "description": "Activity body as HTML." }, "activity_raw_content": { "type": "string", "description": "Activity body as plain text." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when this activity record was written. System-managed and not settable by the caller." }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp when the event occurred. Distinct from `created_at`. Settable on create (`POST /v1/person-activities`) and update (`PATCH /v1/person-activities/{id}`). Defaults to `created_at` when not provided on create." } }, "required": [ "id", "person_id", "activity_type", "activity_content", "activity_raw_content", "created_at", "occurred_at" ] }, "UpdatePersonActivityBody": { "type": "object", "properties": { "activity_content": { "type": "string", "description": "New content for the activity. Format depends on content_type." }, "content_type": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Format of activity_content. \"text\" for plain text (auto-converted to HTML), \"html\" for raw HTML." }, "activity_type": { "type": "string", "minLength": 1, "description": "New activity type key. Must be a valid type registered for the team. Standard values: secondary_note, meeting_note, meeting_transcript, email, interview_note, linkedin_message, text_message, candidate_summary, linkedin_message_response, call_note. Teams can also define custom activity types from Settings → Activity Types; discover the full list with GET /v1/person-activities/types." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for when the event actually occurred (e.g. \"2024-01-10T14:00:00Z\"). This is distinct from `created_at`, which is a system-managed timestamp for when the activity record was written and cannot be changed. Omit to leave the existing event time unchanged." } } }, "UpdatePersonActivityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Updated activity UUID." }, "activity_type": { "type": "string", "description": "Current activity type key after the update." }, "updated_at": { "type": "string", "description": "ISO 8601 update timestamp." } }, "required": [ "id", "activity_type", "updated_at" ] } }, "required": [ "success", "data" ] }, "PersonReferenceTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonReferenceType" } } }, "required": [ "success", "data" ] }, "PersonReferenceType": { "type": "object", "properties": { "type": { "type": "string", "description": "Reference type key. Pass this as `reference_type`." }, "name": { "type": "string", "description": "Display name shown in the app." }, "is_archived": { "type": "boolean", "description": "Archived types cannot be used for new references but may still appear on existing ones." } }, "required": [ "type", "name", "is_archived" ] }, "PersonReferenceCreateRequest": { "type": "object", "properties": { "related_person_id": { "type": "string", "format": "uuid", "description": "UUID of the other person in the reference. Must be a different person in your workspace." }, "reference_type": { "type": "string", "minLength": 1, "description": "Reference type key, such as \"colleague\" or \"manager\". List the keys for your workspace with GET /v1/persons/reference-types." }, "reference_strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "How strong the relationship is: \"low\", \"medium\" or \"high\"." }, "note": { "type": [ "string", "null" ], "description": "Note about the reference, such as what a reference said. Accepts plain text or HTML (bold, italics, lists, links and headings keep their formatting). Pass null to remove the note." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for when the reference actually happened (e.g. \"2024-01-10T14:00:00Z\"). This is distinct from `created_at`, which is a system-managed timestamp for when the reference was written and cannot be set by the caller. Use `occurred_at` to backdate a reference taken earlier. If omitted, it defaults to `created_at`." } }, "required": [ "related_person_id", "reference_type" ] }, "PersonReferenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PersonReference" } }, "required": [ "success", "data" ] }, "PersonReference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Reference UUID." }, "person_id": { "type": "string", "format": "uuid", "description": "UUID of the person in the request path." }, "related_person": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Other person UUID." }, "name": { "type": [ "string", "null" ], "description": "Other person full name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Other person current job title." }, "current_company_name": { "type": [ "string", "null" ], "description": "Other person current employer name." } }, "required": [ "id", "name", "current_job_title", "current_company_name" ], "description": "The other person in the reference." }, "reference_type": { "type": "string", "description": "Reference type key." }, "reference_type_name": { "type": "string", "description": "Display name of the reference type, as shown in the app." }, "reference_strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "How strong the relationship is. Null when not set." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "description": "\"outgoing\" when the reference was added on the person in the path, \"incoming\" when it was added on the other person." }, "note": { "type": [ "string", "null" ], "description": "Plain-text note. Null when the reference has no note." }, "note_html": { "type": [ "string", "null" ], "description": "The note as HTML, keeping its formatting. Null when the reference has no note." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the team member who added the reference. Matches IDs from GET /v1/team-members." }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp for when the reference happened. Defaults to `created_at`; set it on create or update to backdate." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp for when the reference was written." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "person_id", "related_person", "reference_type", "reference_type_name", "reference_strength", "direction", "note", "note_html", "created_by", "occurred_at", "created_at", "updated_at" ] }, "PersonReferenceUpdateRequest": { "type": "object", "properties": { "reference_type": { "type": "string", "minLength": 1, "description": "New reference type key. List the keys for your workspace with GET /v1/persons/reference-types." }, "reference_strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "How strong the relationship is: \"low\", \"medium\" or \"high\". Pass null to clear it." }, "note": { "type": [ "string", "null" ], "description": "Note about the reference, such as what a reference said. Accepts plain text or HTML (bold, italics, lists, links and headings keep their formatting). Pass null to remove the note." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for when the reference actually happened (e.g. \"2024-01-10T14:00:00Z\"). This is distinct from `created_at`, which is a system-managed timestamp for when the reference was written and cannot be changed. Omit to leave the existing time unchanged." } } }, "PersonReferenceDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "PersonsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "Person": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique person UUID. Use as path param in GET /v1/persons/{id}." }, "name": { "type": [ "string", "null" ], "description": "Full name (first + last)." }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "LinkedIn vanity slug (e.g. \"johndoe\" from linkedin.com/in/johndoe)." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title from their profile." }, "current_company_name": { "type": [ "string", "null" ], "description": "Current employer name." }, "current_company_id": { "type": [ "string", "null" ], "description": "UUID of the current employer company. Matches IDs from GET /v1/companies." }, "external_source_id": { "type": [ "string", "null" ], "description": "Identifier from an external system (e.g. HRIS or legacy ATS import ID)." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the person record was created." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the person record was last updated." }, "image_url": { "type": [ "string", "null" ], "description": "Profile photo URL." }, "location": { "type": [ "string", "null" ], "description": "Location string from the profile (e.g. \"San Francisco, CA\")." }, "latitude": { "type": [ "number", "null" ], "description": "Geographic latitude derived from location, for proximity filtering." }, "longitude": { "type": [ "number", "null" ], "description": "Geographic longitude derived from location, for proximity filtering." }, "date_of_last_engagement": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent activity or communication with this person." }, "last_activity_type": { "type": [ "string", "null" ], "description": "Type key of the most recent activity (e.g. \"email\", \"primary_note\", \"linkedin_message\")." }, "do_not_contact": { "type": "boolean", "description": "When true, this person has been marked as do-not-contact." }, "do_not_contact_reason": { "type": [ "string", "null" ], "description": "Free-text reason for the do-not-contact flag, if provided." }, "do_not_contact_expiration_date": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the do-not-contact flag expires. Null when the flag is not set or is indefinite." }, "owner_id": { "type": [ "string", "null" ], "description": "UUID of the team member who owns this person record. Matches IDs from GET /v1/team-members." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/PersonEmailValue" }, "description": "All email addresses on file, each with a type (work, personal, etc.), whether it is preferred, and whether it bounced." }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "All phone numbers on file, each with a type (mobile, work, etc.) and whether it is preferred." }, "preferred_email": { "type": [ "string", "null" ], "description": "Email currently starred as preferred. Campaign enrollment uses this address when set. Null when no email is preferred." }, "preferred_phone": { "type": [ "string", "null" ], "description": "Phone number currently starred as preferred. Null when no phone is preferred." }, "work_experience": { "type": "array", "items": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ], "description": "Null if still in this position." }, "duration_in_months": { "type": [ "number", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "position_type": { "type": [ "string", "null" ], "description": "E.g. \"Full-time\", \"Contract\", \"Intern\"." } }, "required": [ "title", "start_date", "end_date", "duration_in_months", "description", "location", "position_type" ] }, "description": "Positions held at this company (most recent first)." }, "duration_in_months": { "type": [ "number", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ], "description": "UUID of this employer company, if matched. Matches IDs from GET /v1/companies." } }, "required": [ "positions", "duration_in_months", "company_name", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Employment history grouped by company. Included when include contains \"work_experience\"." }, "education_experience": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": [ "string", "null" ], "description": "School or university name." }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "degree": { "type": [ "string", "null" ], "description": "Degree earned (e.g. \"B.S. Computer Science\")." }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ] } }, "required": [ "company_name", "start_date", "end_date", "description", "degree", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Education history. Included when include contains \"education_experience\"." }, "certifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Certification or license name." }, "credential_id": { "type": [ "string", "null" ], "description": "Credential or license number." }, "start_date": { "type": [ "string", "null" ], "description": "Date issued." }, "end_date": { "type": [ "string", "null" ], "description": "Expiry date, null if no expiry." }, "company_name": { "type": [ "string", "null" ], "description": "Issuing organization." }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ] } }, "required": [ "name", "credential_id", "start_date", "end_date", "company_name", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Professional certifications and licenses. Included when include contains \"certifications\"." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/PersonCandidate" }, "description": "Candidate records linking this person to jobs. Included when include contains \"candidates\"; omitted for API-key callers without candidates:read." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom attribute values. Included when include contains \"custom_fields\". Definitions from GET /v1/custom-fields/persons." }, "activities": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" }, "description": "Activities (newest first). Included when include contains \"activities\"; omitted for API-key callers without notes:read. For full pagination use GET /v1/persons/{id}/activities." }, "compensation": { "type": "array", "items": { "$ref": "#/components/schemas/PersonCompensation" }, "description": "Compensation history. Included when include contains \"compensation\"; omitted for API-key callers without compensation:read." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/PersonReference" }, "description": "References for this person, newest first. Included when include contains \"references\"." }, "related_people": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedPerson" }, "description": "Deprecated: use `references`. Included when include contains \"related_people\"." }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/PersonOffer" }, "description": "Job offers across all jobs. Included when include contains \"offers\"; omitted for API-key callers without compensation:read." }, "team_connections": { "type": "array", "items": { "$ref": "#/components/schemas/PersonTeamConnection" }, "description": "Team members who know this person, strongest first. Included when include contains \"team_connections\"; omitted for API-key callers without connections:read." } }, "required": [ "id", "name", "linkedin_public_id", "first_name", "last_name", "current_job_title", "current_company_name", "current_company_id", "external_source_id", "created_at", "updated_at", "image_url", "location", "latitude", "longitude", "date_of_last_engagement", "last_activity_type", "do_not_contact", "do_not_contact_reason", "do_not_contact_expiration_date", "owner_id", "emails", "phones", "preferred_email", "preferred_phone" ] }, "PersonEmailValue": { "allOf": [ { "$ref": "#/components/schemas/PersonContactValue" }, { "type": "object", "properties": { "is_bounced": { "type": "boolean", "description": "True when this address is marked as bounced. Emails and campaigns skip bounced addresses. Change it with POST /v1/persons/email-bounced." } }, "required": [ "is_bounced" ] } ] }, "PersonContactValue": { "type": "object", "properties": { "contact_data_type": { "type": [ "string", "null" ], "description": "Contact category. Values: work, personal, mobile, home, other, or null if unknown." }, "value": { "type": "string", "description": "Email address or phone number string." }, "is_preferred": { "type": "boolean", "description": "True when this is the person's preferred contact of this type. Always present on person responses. Ignored when replacing emails or phone_numbers via PATCH /v1/persons/{id} — use POST /v1/persons/{id}/preferred-email or POST /v1/persons/{id}/preferred-phone instead." } }, "required": [ "contact_data_type", "value" ] }, "PersonCandidate": { "type": "object", "properties": { "candidate_id": { "type": "string", "description": "Candidate record UUID. Use in GET /v1/candidates/{id} for full stage history." }, "job_name": { "type": [ "string", "null" ], "description": "Title of the job this candidate belongs to." }, "job_id": { "type": "string", "description": "UUID of the associated job. Use in GET /v1/jobs/{id} to get pipeline stages." }, "job_client_company_name": { "type": [ "string", "null" ], "description": "Client company name for this job." }, "current_pipeline_stage_name": { "type": [ "string", "null" ], "description": "Name of the current pipeline stage (e.g. \"Technical Interview\")." }, "current_pipeline_stage_id": { "type": [ "string", "null" ], "description": "UUID of the current pipeline stage. Stage IDs come from GET /v1/jobs/{id} → pipeline_stages." }, "is_archived": { "type": "boolean", "description": "True if the candidate was archived/removed from this job." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the person was added as a candidate to this job." }, "sourced_by": { "type": [ "string", "null" ], "description": "UUID of the team member who sourced this candidate. Matches IDs from GET /v1/team-members." }, "owner_id": { "type": [ "string", "null" ], "description": "UUID of the team member who owns this candidate. Matches IDs from GET /v1/team-members." } }, "required": [ "candidate_id", "job_name", "job_id", "job_client_company_name", "current_pipeline_stage_name", "current_pipeline_stage_id", "is_archived", "created_at", "sourced_by", "owner_id" ] }, "Activity": { "type": "object", "properties": { "id": { "type": "string" }, "activity_type": { "type": "string", "description": "Activity type key. Notes: primary_note, secondary_note, interview_note, call_note, meeting_note, client_note, client_created_note, candidate_summary, meeting_transcript, client_rating. Communication: email, email_response, linkedin_message, linkedin_message_response, text_message, whatsapp_message, whatsapp_message_response. Synthetic: task, calendar_event, sequence_enrollment, pipeline_status, assessment, person_reference." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when this activity record was written. System-managed and not settable by the caller." }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp when the event occurred. Distinct from `created_at`, which is when the record was written. For person activities this can be set on create/update via POST/PATCH /v1/person-activities. For synthetic timeline items (tasks, calendar events, pipeline changes, etc.) it is derived from the source event." }, "updated_at": { "type": [ "string", "null" ], "description": "Last modification timestamp. Compare with created_at to detect edited activities." }, "activity_content": { "type": "string", "description": "Plain text content — the body/summary of the activity." }, "activity_content_match": { "type": "string", "description": "Present only when a `search` filter matched this activity. The passage where the search terms cluster, so the relevant section surfaces even when activity_content is long." }, "team_member": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": "string", "description": "Team member full name." } }, "required": [ "id", "name" ], "description": "Team member who created or owns this activity." }, "job": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Job UUID. Use in GET /v1/jobs/{id} for full job details." }, "title": { "type": "string", "description": "Job title." }, "company_name": { "type": [ "string", "null" ], "description": "Client company name for this job." } }, "required": [ "id", "title", "company_name" ], "description": "Associated job, if any." }, "email_details": { "type": "object", "properties": { "subject": { "type": [ "string", "null" ] }, "from_email": { "type": [ "string", "null" ] }, "to_email": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "\"sent\", \"opened\", \"replied\", \"bounced\", etc." } }, "required": [ "subject", "from_email", "to_email", "status" ], "description": "Present only when activity_type is \"email\" or \"email_response\"." }, "whatsapp_details": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "description": "Internal WhatsApp conversation UUID. Used for grouping; this is not a provider identifier." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "inbound = received from the person, outbound = sent by the recruiter." }, "is_deleted": { "type": "boolean", "description": "True when the WhatsApp message was deleted. Text is omitted and the activity remains as a tombstone." }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp when the WhatsApp message occurred." }, "text": { "type": [ "string", "null" ], "description": "Message text when the caller can read the activity. Null for tombstones. Omitted in compact mode." } }, "required": [ "conversation_id", "direction", "is_deleted", "occurred_at" ], "description": "Present only when activity_type is \"whatsapp_message\" or \"whatsapp_message_response\"." }, "task_details": { "type": "object", "properties": { "status": { "type": "string", "description": "\"open\" or \"completed\"." }, "due_date": { "type": [ "string", "null" ], "description": "ISO 8601 due date." }, "task_type": { "type": [ "string", "null" ], "description": "\"follow_up\", \"call\", \"email\", \"meeting\", \"other\", etc." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": "string", "description": "Team member full name." } }, "required": [ "id", "name" ] } }, "required": [ "status", "due_date", "task_type", "assigned_to" ], "description": "Present only when activity_type is \"task\"." }, "calendar_event_details": { "type": "object", "properties": { "start_time": { "type": "string", "description": "ISO 8601 start time." }, "end_time": { "type": "string", "description": "ISO 8601 end time." }, "location": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Event description." }, "conferencing": { "description": "Conferencing details (provider, URL)." }, "is_shadow_invite": { "type": "boolean", "description": "When true, the event exists only on the organizer's calendar. Attendees are linked for activity tracking but were not invited and cannot see it on their calendar." } }, "required": [ "start_time", "end_time", "location", "description", "is_shadow_invite" ], "description": "Present only when activity_type is \"calendar_event\"." }, "sequence_enrollment_details": { "type": "object", "properties": { "sequence_id": { "type": "string" }, "sequence_name": { "type": "string" }, "status": { "type": [ "string", "null" ], "description": "\"active\", \"completed\", \"paused\", \"bounced\", \"replied\", \"failed\", etc." } }, "required": [ "sequence_id", "sequence_name", "status" ], "description": "Present only when activity_type is \"sequence_enrollment\"." }, "pipeline_status_details": { "type": "object", "properties": { "stage_name": { "type": [ "string", "null" ] }, "is_rejection_stage": { "type": [ "boolean", "null" ] }, "entered_at": { "type": "string", "description": "ISO 8601 when candidate entered this stage." }, "exited_at": { "type": [ "string", "null" ], "description": "Null if still in stage." }, "reason_text": { "type": [ "string", "null" ], "description": "Free-text rejection or stage-change reason." }, "rejection_reason": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Rejection reason UUID." }, "reason": { "type": "string", "description": "Rejection reason label." } }, "required": [ "id", "reason" ], "description": "Selected rejection reason. Null when no predefined rejection reason was recorded." } }, "required": [ "stage_name", "is_rejection_stage", "entered_at", "exited_at", "reason_text", "rejection_reason" ], "description": "Present only when activity_type is \"pipeline_status\"." }, "assessment_details": { "type": "object", "properties": { "score": { "type": [ "number", "null" ], "description": "Rater's overall score, 0..rating_scale." }, "template_name": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assessment template UUID." }, "rating_scale": { "type": [ "number", "null" ], "description": "Maximum possible score on this template (3, 4, 5 or 10). Use to interpret `score` and `criteria[].rating`." }, "assessor": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Team member UUID. Matches IDs from GET /v1/team-members." }, "name": { "type": "string", "description": "Team member full name." } }, "required": [ "id", "name" ] }, "candidate_id": { "type": [ "string", "null" ], "description": "Candidate ID for this assessment." }, "assessment_content": { "type": "string", "description": "Concatenated plain-text view of overall and per-criterion comments, in display order. Useful for previews and search; numeric scores live in `score` and `criteria[].rating`." }, "overall_comment": { "type": [ "object", "null" ], "properties": { "content_text": { "type": "string", "description": "Plain-text view of the comment, derived from the tiptap doc." } }, "required": [ "content_text" ], "description": "Rater's overall comment. Null when no comment was given." }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Criterion UUID." }, "name": { "type": "string", "description": "Criterion display name." }, "importance": { "type": "string", "enum": [ "must_have", "nice_to_have" ], "description": "Whether this criterion is a must-have or nice-to-have on the template." }, "position": { "type": "number", "description": "Display order on the template (smaller = shown first)." }, "rating": { "type": [ "number", "null" ], "description": "Rater's score for this criterion (0..rating_scale, half-step). Null when only a comment was given." }, "comment": { "type": [ "object", "null" ], "properties": { "content_text": { "type": "string", "description": "Plain-text view of the comment, derived from the tiptap doc." } }, "required": [ "content_text" ], "description": "Per-criterion comment. Null when no comment was given." } }, "required": [ "id", "name", "importance", "position", "rating", "comment" ] }, "description": "Per-criterion ratings sorted by template position. Empty array when the template has no criteria." } }, "required": [ "score", "template_name", "template_id", "rating_scale", "assessor", "candidate_id", "assessment_content", "overall_comment", "criteria" ], "description": "Present only when activity_type is \"assessment\"." }, "person_reference_details": { "type": "object", "properties": { "reference_id": { "type": "string", "format": "uuid", "description": "Reference UUID. Use with PATCH or DELETE /v1/persons/{id}/references/{reference_id}." }, "reference_type": { "type": "string", "description": "Reference type key." }, "reference_type_name": { "type": "string", "description": "Display name of the reference type, as shown in the app." }, "reference_strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "How strong the relationship is. Null when not set." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "description": "\"outgoing\" when the reference was added on this person, \"incoming\" when it was added on the related person." }, "related_person": { "type": "object", "properties": { "id": { "type": "string", "description": "Related person UUID." }, "name": { "type": [ "string", "null" ], "description": "Related person full name." } }, "required": [ "id", "name" ], "description": "The other person in the reference." }, "note": { "type": [ "string", "null" ], "description": "Plain-text note about the reference. Null when there is none." } }, "required": [ "reference_id", "reference_type", "reference_type_name", "reference_strength", "direction", "related_person", "note" ], "description": "Present only when activity_type is \"person_reference\": a relation (shown as a Reference in the app) added between this person and another." } }, "required": [ "id", "activity_type", "created_at", "occurred_at", "updated_at", "activity_content", "team_member", "job" ] }, "PersonCompensation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Compensation record UUID." }, "compensation_type": { "type": [ "string", "null" ], "enum": [ "desired", "actual", "minimum" ], "description": "Type of compensation: \"desired\", \"actual\", or \"minimum\"." }, "currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\"). Defaults to USD." }, "current_compensation_base": { "type": [ "number", "null" ], "description": "Base salary amount." }, "current_compensation_bonus": { "type": [ "number", "null" ], "description": "Bonus cash amount. When bonus_percent is set, this is the cash value of that percentage of base salary." }, "bonus_percent": { "type": [ "number", "null" ], "description": "Bonus as a percentage of base salary. Null when the bonus is a fixed cash amount." }, "equity_percent": { "type": [ "number", "null" ], "description": "Equity grant as a percentage." }, "equity_amount": { "type": [ "number", "null" ], "description": "Equity grant as a fixed amount." }, "compensation_year": { "type": [ "number", "null" ], "description": "The year this compensation applies to (e.g. 2025 for historical comp)." }, "total_estimated_compensation": { "type": [ "number", "null" ], "description": "Total estimated annual compensation (base + bonus + equity)." }, "note": { "type": [ "string", "null" ], "description": "Free-text compensation notes." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated job UUID, if this compensation is job-specific." }, "job_name": { "type": [ "string", "null" ], "description": "Title of the associated job." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "compensation_type", "currency_code", "current_compensation_base", "current_compensation_bonus", "bonus_percent", "equity_percent", "equity_amount", "compensation_year", "total_estimated_compensation", "note", "job_id", "job_name", "created_at", "updated_at" ] }, "RelatedPerson": { "type": "object", "properties": { "relation_id": { "type": "string", "description": "Relation record UUID." }, "person_id": { "type": "string", "description": "UUID of the related person." }, "name": { "type": [ "string", "null" ], "description": "Related person full name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Related person current job title." }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "Related person LinkedIn vanity slug." }, "current_company_name": { "type": [ "string", "null" ], "description": "Related person current employer name." }, "current_company_id": { "type": [ "string", "null" ], "description": "Related person current employer UUID." }, "relation_type": { "type": "string", "description": "Type of relation (e.g. \"spouse\", \"colleague\", \"referral\")." }, "relation_type_name": { "type": "string", "description": "Display name of the relation type, as shown in the app." }, "relation_strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "How strong the relationship is. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Plain-text note about the relation." }, "note_html": { "type": [ "string", "null" ], "description": "The note as HTML, keeping its formatting. Null when the relation has no note." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "description": "\"outgoing\" if this person created the relation, \"incoming\" if the other person did." }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp for when the reference happened. Defaults to `created_at`." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "relation_id", "person_id", "name", "current_job_title", "linkedin_public_id", "current_company_name", "current_company_id", "relation_type", "relation_type_name", "relation_strength", "note", "note_html", "direction", "occurred_at", "created_at" ] }, "PersonOffer": { "type": "object", "properties": { "id": { "type": "string", "description": "Offer record UUID." }, "job_id": { "type": "string", "description": "Associated job UUID." }, "job_name": { "type": [ "string", "null" ], "description": "Job title." }, "job_company_name": { "type": [ "string", "null" ], "description": "Client company name for the job." }, "candidate_id": { "type": "string", "description": "Candidate record UUID." }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "status_type": { "type": "string", "enum": [ "pending", "accepted", "rejected", "rescinded" ], "description": "Lifecycle category of the offer status: pending, accepted, rejected, or rescinded." } }, "required": [ "id", "name", "color", "status_type" ], "description": "Current offer status." }, "extended_date": { "type": [ "string", "null" ], "description": "ISO 8601 date offer was extended." }, "accepted_date": { "type": [ "string", "null" ], "description": "ISO 8601 date offer was accepted." }, "candidate_start_date": { "type": [ "string", "null" ], "description": "ISO 8601 anticipated start date." }, "compensation_currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code." }, "compensation_base": { "type": [ "number", "null" ], "description": "Base salary offered." }, "compensation_bonus": { "type": [ "number", "null" ], "description": "Bonus offered." }, "bonus_type": { "type": [ "string", "null" ], "description": "\"fixed\" or \"percent\"." }, "annual_equity_grant_percent": { "type": [ "number", "null" ] }, "annual_equity_grant_amount": { "type": [ "number", "null" ] }, "initial_equity_grant_percent": { "type": [ "number", "null" ] }, "initial_equity_grant_amount": { "type": [ "number", "null" ] }, "relocation_bonus": { "type": [ "number", "null" ], "description": "Relocation bonus amount." }, "sign_on_bonus": { "type": [ "number", "null" ], "description": "Sign-on bonus amount." }, "total_estimated_compensation": { "type": [ "number", "null" ], "description": "Total estimated compensation." }, "note": { "type": [ "string", "null" ], "description": "Offer notes." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "job_id", "job_name", "job_company_name", "candidate_id", "status", "extended_date", "accepted_date", "candidate_start_date", "compensation_currency", "compensation_base", "compensation_bonus", "bonus_type", "annual_equity_grant_percent", "annual_equity_grant_amount", "initial_equity_grant_percent", "initial_equity_grant_amount", "relocation_bonus", "sign_on_bonus", "total_estimated_compensation", "note", "created_at", "updated_at" ] }, "PersonTeamConnection": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member who knows this person." }, "team_member_name": { "type": "string", "description": "Team member full name." }, "is_former_member": { "type": "boolean", "description": "True when the team member has left the workspace. Former members cannot make introductions." }, "strength": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high" ], "description": "Relationship strength between this team member and the person: set automatically from replies, meetings and notes, unless someone set it by hand." }, "linkedin_connected_on": { "type": [ "string", "null" ], "description": "Date the team member connected with the person on LinkedIn (YYYY-MM-DD), from their uploaded connections." } }, "required": [ "team_member_id", "team_member_name", "is_former_member", "strength", "linkedin_connected_on" ] }, "PersonCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Full name (required). Used as display name across the system." }, "first_name": { "type": "string", "description": "First name. Auto-split from name if omitted." }, "last_name": { "type": "string", "description": "Last name. Auto-split from name if omitted." }, "linkedin_url": { "type": "string", "format": "uri", "description": "**Strongly recommended.** LinkedIn profile URL (e.g. \"https://linkedin.com/in/johndoe\") is the deduplication key for this endpoint. When present, an existing person with that profile is matched and updated (never duplicated), including when `job_id` is used to add a candidacy. Without it, a duplicate is only caught when the name matches an existing person along with their email and/or phone (see the endpoint description); otherwise a new person is created. Enrichment is also skipped without a LinkedIn URL." }, "current_job_title": { "type": "string", "description": "Current job title." }, "location": { "type": "string", "description": "Location (e.g. city, region, or country)." }, "company_name": { "type": "string", "description": "Current employer company name." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Additional email addresses." }, "work_email": { "type": "string", "format": "email", "description": "Primary work email." }, "work_phone": { "type": "string", "description": "Work phone number." }, "personal_email": { "type": "string", "format": "email", "description": "Personal email address." }, "mobile_phone": { "type": "string", "description": "Mobile phone number." }, "phone_numbers": { "type": "array", "items": { "type": "string" }, "description": "Additional phone numbers." }, "notes": { "type": "string", "description": "Initial note to attach to the person record." }, "job_id": { "type": "string", "description": "Job UUID to add this person to that job pipeline as a candidate (creates the candidacy). When linkedin_url is provided, works whether the person is new or already exists (matched by linkedin_url, never duplicated). Without linkedin_url, a new person may be created unless it is automatically merged into a matching existing person, in which case that person is added to the job. Get IDs from POST /v1/jobs/search." }, "job_name": { "type": "string", "description": "Job title to match and add this person to that job pipeline as a candidate. Used when job_id is not provided." }, "client_name": { "type": "string", "description": "Company name to associate this person as a client contact." }, "client_id": { "type": "string", "description": "Company UUID for client contact association. Get IDs from GET /v1/companies." }, "external_source_id": { "type": "string", "description": "Identifier from an external system (e.g. HRIS or legacy ATS). A new person is never automatically merged into an existing person that has a different external_source_id." }, "enrich_record": { "type": "boolean", "description": "When true, triggers background enrichment via data providers after creation." }, "person_owner": { "type": "string", "format": "uuid", "description": "UUID of the team member to assign as owner of this person. Get IDs from GET /v1/team-members. If omitted, the caller is auto-assigned when authenticated as a team member. If the team member is not found, a warning is logged but person creation still proceeds." }, "sourced_by": { "type": "string", "format": "uuid", "description": "UUID of the team member who sourced this candidate, recorded as \"Sourced by\" on the new candidacy. Get IDs from GET /v1/team-members. Requires `job_id`. Only applies to API-key requests; requests made as a signed-in user (session or OAuth, including MCP) always credit that user. If the person is already a candidate on the job, the existing sourcer is kept. When `person_owner` is omitted, this team member also becomes the owner of a newly created person and candidacy." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/persons." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types (text, number, date, url, boolean): the value to set, or null to clear. For single-select: pass the tag NAME (e.g. \"Remote\", \"On-site\") or the tag option UUID from GET /v1/custom-fields/persons. A new tag is auto-created only for a name that does not exist yet; an unknown UUID is ignored. Null to clear." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES (e.g. [\"Engineer\", \"Designer\"]) or tag option UUIDs from GET /v1/custom-fields/persons. A new tag is auto-created only for a name that does not exist yet; an unknown UUID is ignored. Duplicates silently skipped." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields. Get IDs from GET /v1/team-members." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields. Get IDs from POST /v1/companies/search." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all existing values for this multi-select, multi-team-member, or multi-company attribute. Combine with add_values/add_team_member_ids/add_company_ids to replace all values in one call." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to set, in the same shape as PATCH /v1/persons/{id}. Get attribute definitions from GET /v1/custom-fields/persons. When `linkedin_url` matches an existing person, the values are written to that person. If a value is invalid, the person is still saved and the error message includes its ID so the fields can be retried with PATCH." } }, "required": [ "name" ] }, "PersonCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PersonCreateResponseData" } }, "required": [ "success", "data" ] }, "PersonCreateResponseData": { "type": "object", "properties": { "id": { "type": "string", "description": "Created person UUID." }, "name": { "type": "string", "description": "Person full name." }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "LinkedIn vanity slug." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title." }, "company_name": { "type": [ "string", "null" ], "description": "Current employer name." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "Email addresses saved." }, "location": { "type": [ "string", "null" ], "description": "Location (e.g. city, region, or country)." }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "Phone numbers saved." }, "candidate_id": { "type": [ "string", "null" ], "description": "Candidate UUID if the person was added to a job. Null if no job was specified." }, "client_contact_id": { "type": [ "string", "null" ], "description": "Client contact UUID if the person was linked to a client company. Null otherwise." }, "external_source_id": { "type": [ "string", "null" ], "description": "External system identifier, if provided." } }, "required": [ "id", "name", "linkedin_public_id", "current_job_title", "company_name", "emails", "location", "phones", "candidate_id", "client_contact_id", "external_source_id" ] }, "PersonsSearchBody": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records to return (1–100). Defaults to 100." }, "sort_by": { "type": "string", "description": "Sort column. Values: name, created_at, updated_at, current_job_title, company, location, date_of_last_engagement, person_owner, last_activity_type, contact_email. Job-context columns (require job_id or single job_ids_included): pipeline_stage, stage_date, added_to_job_at, rating, rating_note, candidate_owner. Custom field sorting: custom_. Defaults to created_at.", "example": "created_at" }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "email": { "type": "string", "format": "email", "description": "Filter by exact email address match." }, "name": { "type": "string", "description": "Ranked person lookup. Matches name, title, company, and location; 1-3 word queries boost the name field. Returns the top matches (up to 50), not every substring hit. Use keywords for exhaustive profile-text search." }, "phone": { "type": "string", "description": "Filter by phone number. Tiered matching: exact → normalized → last-7-digits." }, "linkedin_url": { "type": "string", "pattern": "^https?:\\/\\/(?:[a-z]{2}\\.)?(?:www\\.)?linkedin\\.com\\/in\\/[^?#\\s]+\\/?(?:[?#][^\\s]*)?$", "description": "Filter by LinkedIn profile URL. Must be a valid LinkedIn profile URL (https://www.linkedin.com/in/...)" }, "vector_search": { "type": "string", "minLength": 5, "description": "AI semantic search query (min 5 chars). Searches profile text via vector embeddings." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "work_experience", "education_experience", "certifications", "candidates", "custom_fields", "activities", "compensation", "references", "related_people", "offers", "team_connections" ] }, "description": "Sections to embed in each person record. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, references, offers, team_connections (related_people is a deprecated alias for references in the older shape). Omit for base fields only. Pass empty array [] for base fields explicitly. For API-key callers, unavailable requested sections are omitted: activities requires notes:read, candidates requires candidates:read, compensation and offers require compensation:read, and team_connections requires connections:read." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Substring search across profile text. For looking up a specific person by name, use name instead." }, "job_id": { "type": "string", "format": "uuid", "description": "Single job UUID to scope results to candidates in this job. Enables job-context sort columns (pipeline_stage, stage_date, etc.). Get job IDs from POST /v1/jobs/search. For multi-job filtering, use job_ids_included." }, "job_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Only include candidates from these jobs. Get IDs from POST /v1/jobs/search." }, "job_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude candidates from these jobs." }, "filter_out_if_not_in_job": { "type": "boolean", "description": "When true, only return persons who are candidates in at least one of job_ids_included." }, "exclude_archived_jobs": { "type": "boolean", "default": true, "description": "Exclude candidates from archived jobs. Defaults to true." }, "job_titles_included": { "type": "array", "items": { "type": "string" }, "description": "Include persons whose current_job_title partially matches any of these strings." }, "job_titles_excluded": { "type": "array", "items": { "type": "string" }, "description": "Exclude persons whose current_job_title matches any of these strings." }, "departments_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons in jobs with these department UUIDs." }, "departments_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons in jobs with these department UUIDs." }, "current_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons currently at these companies. Get IDs from GET /v1/companies." }, "current_company_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons currently at these companies." }, "past_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons who previously worked at these companies." }, "past_company_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons who previously worked at these companies." }, "pipeline_stage_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons currently in these pipeline stages. Get stage IDs from GET /v1/jobs/{id} → pipeline_stages." }, "pipeline_stage_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons currently in these pipeline stages." }, "pipeline_stage_history_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons who were ever in these stages (historical)." }, "pipeline_stage_history_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons who were ever in these stages (historical)." }, "rejection_reason_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons whose current rejection stage has one of these rejection reasons. Get reason IDs from the rejection reasons configured for your team." }, "rejection_reason_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons whose current rejection stage has one of these rejection reasons." }, "job_page_pipeline_stages_in": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter by current pipeline stage within a specific job context. Stage IDs from GET /v1/jobs/{id} → pipeline_stages." }, "job_page_pipeline_stages_ex": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude these pipeline stages within a specific job context." }, "activity_types_included": { "type": "array", "items": { "type": "string" }, "description": "Include persons with activities of these types (e.g. \"email\", \"secondary_note\"). Get type keys from GET /v1/person-activities/types. Combine with activity_owner_ids_* and activity_date_* to require one activity that matches all of them, e.g. a given type in the last 7 days." }, "activity_types_excluded": { "type": "array", "items": { "type": "string" }, "description": "Exclude persons with activities of these types. When activity owner or date filters are set, only activities by those owners or in that window count, so activity_types_excluded=[\"call\"] with activity_date_type=within_last, activity_date_value=30, activity_date_unit=days returns persons with no call in the last 30 days." }, "activity_owner_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Only count activities logged by these team members. Get IDs from GET /v1/team-members. Activity type, owner and date filters apply to the same activity, so combined with activity_types_included this returns persons with an activity of that type logged by one of these team members. Set on its own to return persons with any activity logged by these team members." }, "activity_owner_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Ignore activities logged by these team members when matching the other activity filters." }, "activity_date_type": { "type": "string", "enum": [ "within_last", "custom_range" ], "description": "Only count activities that happened in a date window. within_last uses activity_date_value and activity_date_unit (e.g. the last 7 days); custom_range uses activity_date_start_date and/or activity_date_end_date. Applies to the same activity as the activity type and owner filters. Set on its own to return persons with any activity in the window." }, "activity_date_value": { "type": "integer", "exclusiveMinimum": 0, "description": "Length of the within_last window, e.g. 7 with activity_date_unit=days for the past week.", "example": 7 }, "activity_date_unit": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Time unit for activity_date_value." }, "activity_date_start_date": { "type": "string", "description": "Earliest activity date for custom_range (ISO 8601, inclusive).", "example": "2026-09-01T00:00:00Z" }, "activity_date_end_date": { "type": "string", "description": "Latest activity date for custom_range (ISO 8601, inclusive).", "example": "2026-09-30T23:59:59Z" }, "activity_content_keywords": { "type": "array", "items": { "type": "string" }, "description": "Filter by keywords found in notes and document text. API keys also need `notes:read` and `documents:read`; requests without both scopes are rejected." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "Include persons with documents of any of these type keys. Omit this and has_any_document to ignore documents." }, "has_any_document": { "type": "boolean", "description": "When true, include only persons with at least one document. This also applies when document_types is provided." }, "off_limits": { "type": "string", "enum": [ "all", "hide", "show" ], "description": "Controls off-limits persons: all keeps everyone, hide excludes them, and show returns only them." }, "off_limits_sources": { "type": "array", "items": { "type": "string", "enum": [ "person", "company" ] }, "minItems": 1, "description": "Choose which Do Not Contact statuses count as off-limits: person, company, or both. Defaults to both." }, "known_by_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include only persons known by at least one of these team members, from their uploaded LinkedIn connections. Get IDs from GET /v1/team-members. Former team members can be picked here. API keys need the connections:read scope." }, "known_by_any_team_member": { "type": "boolean", "description": "When true, include only persons known by at least one current team member. Ignored when known_by_team_member_ids is set. API keys need the connections:read scope." }, "min_connection_strength": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Include only persons whose connection to a team member is at least this strong. Combines with known_by_team_member_ids; on its own it means any current team member. API keys need the connections:read scope." }, "person_owner_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons owned by these team members. Get IDs from GET /v1/team-members." }, "person_owner_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons owned by these team members." }, "candidate_owner_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons whose candidate record is owned by these team members." }, "candidate_owner_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons whose candidate record is owned by these team members." }, "sourced_by_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter by team members who sourced the candidate. Get IDs from GET /v1/team-members." }, "sourced_by_include_empty": { "type": "boolean", "description": "When true, also include candidates with no source assigned." }, "list_ids_included": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Include persons in these saved lists." }, "list_ids_excluded": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Exclude persons in these saved lists." }, "hide_client_contacts": { "type": "boolean", "description": "When true, exclude persons who are client contacts. Invalid when combined with only_client_contacts=true." }, "only_client_contacts": { "type": "boolean", "description": "When true, return only persons who are client contacts (have a non-deleted client_contacts row for this team). Invalid when combined with hide_client_contacts=true." }, "contact_email_filter": { "type": "string", "enum": [ "has_email", "missing_email" ], "description": "\"has_email\" returns only persons with at least one email; \"missing_email\" returns only persons with no email." }, "engagement_type": { "type": "string", "enum": [ "engaged_within", "not_engaged_within", "custom_range", "never_engaged" ], "description": "Engagement recency filter type." }, "engagement_value": { "type": "number", "description": "Numeric value for engagement window (e.g. 30 for \"30 days\")." }, "engagement_unit": { "type": "string", "enum": [ "days", "months", "years" ], "description": "Time unit for engagement_value." }, "engagement_start_date": { "type": "string", "description": "Start of custom engagement date range (ISO 8601)." }, "engagement_end_date": { "type": "string", "description": "End of custom engagement date range (ISO 8601)." }, "added_to_job_start_date": { "type": "string", "description": "Only include candidates added to a job after this date (ISO 8601)." }, "added_to_job_end_date": { "type": "string", "description": "Only include candidates added to a job before this date (ISO 8601)." }, "locations_included": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "bounds": { "type": "object", "properties": { "south": { "type": "number" }, "west": { "type": "number" }, "north": { "type": "number" }, "east": { "type": "number" } }, "required": [ "south", "west", "north", "east" ] } }, "required": [ "value", "label", "lat", "lng", "bounds" ] }, "description": "Include persons within these geographic bounding boxes." }, "locations_excluded": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "bounds": { "type": "object", "properties": { "south": { "type": "number" }, "west": { "type": "number" }, "north": { "type": "number" }, "east": { "type": "number" } }, "required": [ "south", "west", "north", "east" ] } }, "required": [ "value", "label", "lat", "lng", "bounds" ] }, "description": "Exclude persons within these geographic bounding boxes." }, "select_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions." }, "excluded_values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/persons." }, "numeric_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}." }, "min": { "type": [ "number", "null" ], "description": "Minimum value (inclusive). Null for no lower bound." }, "max": { "type": [ "number", "null" ], "description": "Maximum value (inclusive). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/persons." }, "date_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}." }, "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/persons." }, "team_member_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to include. Get IDs from GET /v1/team-members." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified team members (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no team member assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/persons, team member IDs from GET /v1/team-members." }, "company_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-company type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to include. Get IDs from GET /v1/companies/search or search-companies." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified companies (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no company assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Filter by multi-company custom fields. Get attribute_id from GET /v1/custom-fields/persons, company IDs from POST /v1/companies/search." }, "created_at_gte": { "type": "string", "description": "Only include persons created on or after this date (ISO 8601)." }, "created_at_lte": { "type": "string", "description": "Only include persons created on or before this date (ISO 8601)." }, "updated_at_gte": { "type": "string", "description": "Only include persons updated on or after this date (ISO 8601)." }, "updated_at_lte": { "type": "string", "description": "Only include persons updated on or before this date (ISO 8601)." }, "current_company_attribute_filters": { "type": "object", "properties": { "select_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID. Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions." }, "excluded_values": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tag option UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Company select/tag attribute filters. Get attribute_id from GET /v1/custom-fields/companies." }, "numeric_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}." }, "min": { "type": [ "number", "null" ], "description": "Minimum value (inclusive). Null for no lower bound." }, "max": { "type": [ "number", "null" ], "description": "Maximum value (inclusive). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Company numeric attribute filters." }, "date_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}." }, "start_date": { "type": [ "string", "null" ], "description": "Start of date range (ISO 8601). Null for no lower bound." }, "end_date": { "type": [ "string", "null" ], "description": "End of date range (ISO 8601). Null for no upper bound." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no value set." } }, "required": [ "attribute_id" ] }, "description": "Company date attribute filters." }, "team_member_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to include. Get IDs from GET /v1/team-members." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Team member UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified team members (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no team member assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Company team-member attribute filters." }, "company_attribute_filters": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Attribute definition UUID (multi-company type). Get from GET /v1/custom-fields/{entity}." }, "values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to include. Get IDs from GET /v1/companies/search or search-companies." }, "excluded_values": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Company UUIDs to exclude." }, "require_all": { "type": "boolean", "default": false, "description": "When true, record must have ALL specified companies (AND logic)." }, "include_empty": { "type": "boolean", "default": false, "description": "When true, also include records with no company assigned for this attribute." } }, "required": [ "attribute_id" ] }, "description": "Company multi-company attribute filters." } }, "description": "Filter by company-level custom attributes on the person's current employer. Get attribute_id from GET /v1/custom-fields/companies." } } }, "PersonByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PersonDetails" } }, "required": [ "success", "data" ] }, "PersonDetails": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique person UUID. Use as path param in GET /v1/persons/{id}." }, "name": { "type": [ "string", "null" ], "description": "Full name (first + last)." }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "LinkedIn vanity slug (e.g. \"johndoe\" from linkedin.com/in/johndoe)." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title from their profile." }, "current_company_name": { "type": [ "string", "null" ], "description": "Current employer name." }, "current_company_id": { "type": [ "string", "null" ], "description": "UUID of the current employer company. Matches IDs from GET /v1/companies." }, "external_source_id": { "type": [ "string", "null" ], "description": "Identifier from an external system (e.g. HRIS or legacy ATS import ID)." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the person record was created." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the person record was last updated." }, "image_url": { "type": [ "string", "null" ], "description": "Profile photo URL." }, "location": { "type": [ "string", "null" ], "description": "Location string from the profile (e.g. \"San Francisco, CA\")." }, "latitude": { "type": [ "number", "null" ], "description": "Geographic latitude derived from location, for proximity filtering." }, "longitude": { "type": [ "number", "null" ], "description": "Geographic longitude derived from location, for proximity filtering." }, "date_of_last_engagement": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent activity or communication with this person." }, "last_activity_type": { "type": [ "string", "null" ], "description": "Type key of the most recent activity (e.g. \"email\", \"primary_note\", \"linkedin_message\")." }, "do_not_contact": { "type": "boolean", "description": "When true, this person has been marked as do-not-contact." }, "do_not_contact_reason": { "type": [ "string", "null" ], "description": "Free-text reason for the do-not-contact flag, if provided." }, "do_not_contact_expiration_date": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the do-not-contact flag expires. Null when the flag is not set or is indefinite." }, "owner_id": { "type": [ "string", "null" ], "description": "UUID of the team member who owns this person record. Matches IDs from GET /v1/team-members." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/PersonEmailValue" }, "description": "All email addresses on file, each with a type (work, personal, etc.), whether it is preferred, and whether it bounced." }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "All phone numbers on file, each with a type (mobile, work, etc.) and whether it is preferred." }, "preferred_email": { "type": [ "string", "null" ], "description": "Email currently starred as preferred. Campaign enrollment uses this address when set. Null when no email is preferred." }, "preferred_phone": { "type": [ "string", "null" ], "description": "Phone number currently starred as preferred. Null when no phone is preferred." }, "work_experience": { "type": "array", "items": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ], "description": "Null if still in this position." }, "duration_in_months": { "type": [ "number", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "position_type": { "type": [ "string", "null" ], "description": "E.g. \"Full-time\", \"Contract\", \"Intern\"." } }, "required": [ "title", "start_date", "end_date", "duration_in_months", "description", "location", "position_type" ] }, "description": "Positions held at this company (most recent first)." }, "duration_in_months": { "type": [ "number", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ], "description": "UUID of this employer company, if matched. Matches IDs from GET /v1/companies." } }, "required": [ "positions", "duration_in_months", "company_name", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Employment history grouped by company. Included when include contains \"work_experience\"." }, "education_experience": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": [ "string", "null" ], "description": "School or university name." }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "degree": { "type": [ "string", "null" ], "description": "Degree earned (e.g. \"B.S. Computer Science\")." }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ] } }, "required": [ "company_name", "start_date", "end_date", "description", "degree", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Education history. Included when include contains \"education_experience\"." }, "certifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Certification or license name." }, "credential_id": { "type": [ "string", "null" ], "description": "Credential or license number." }, "start_date": { "type": [ "string", "null" ], "description": "Date issued." }, "end_date": { "type": [ "string", "null" ], "description": "Expiry date, null if no expiry." }, "company_name": { "type": [ "string", "null" ], "description": "Issuing organization." }, "company_linkedin_url": { "type": [ "string", "null" ] }, "company_linkedin_id": { "type": [ "number", "null" ] }, "company_id": { "type": [ "string", "null" ] } }, "required": [ "name", "credential_id", "start_date", "end_date", "company_name", "company_linkedin_url", "company_linkedin_id", "company_id" ] }, "description": "Professional certifications and licenses. Included when include contains \"certifications\"." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/PersonCandidate" }, "description": "Candidate records. Included when include contains \"candidates\"; omitted for API-key callers without candidates:read." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Custom attribute values. Included when include contains \"custom_fields\". Definitions from GET /v1/custom-fields/persons." }, "activities": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" }, "description": "Activities (newest first). Included when include contains \"activities\"; omitted for API-key callers without notes:read. For full pagination use GET /v1/persons/{id}/activities." }, "compensation": { "type": "array", "items": { "$ref": "#/components/schemas/PersonCompensation" }, "description": "Compensation history. Included when include contains \"compensation\"; omitted for API-key callers without compensation:read." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/PersonReference" }, "description": "References for this person, newest first. Included when include contains \"references\"." }, "related_people": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedPerson" }, "description": "Deprecated: use `references`. Included when include contains \"related_people\"." }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/PersonOffer" }, "description": "Job offers across all jobs. Included when include contains \"offers\"; omitted for API-key callers without compensation:read." }, "team_connections": { "type": "array", "items": { "$ref": "#/components/schemas/PersonTeamConnection" }, "description": "Team members who know this person, strongest first. Included when include contains \"team_connections\"; omitted for API-key callers without connections:read." } }, "required": [ "id", "name", "linkedin_public_id", "first_name", "last_name", "current_job_title", "current_company_name", "current_company_id", "external_source_id", "created_at", "updated_at", "image_url", "location", "latitude", "longitude", "date_of_last_engagement", "last_activity_type", "do_not_contact", "do_not_contact_reason", "do_not_contact_expiration_date", "owner_id", "emails", "phones", "preferred_email", "preferred_phone" ] }, "UpdatePersonRequest": { "type": "object", "properties": { "linkedin_url": { "type": "string", "description": "LinkedIn profile URL." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "Replace all email addresses. Cannot be combined with work_email or personal_email." }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PersonContactValue" }, "description": "Replace all phone numbers. Cannot be combined with work_phone or mobile_phone." }, "name": { "type": "string", "description": "Full name." }, "first_name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "current_job_title": { "type": "string", "description": "Current job title." }, "company_name": { "type": "string", "description": "Current employer company name." }, "location": { "type": "string", "description": "Location (e.g. city, region, or country)." }, "linkedin_headline": { "type": "string", "description": "LinkedIn headline text." }, "address": { "type": "string", "description": "Physical/mailing address." }, "enrich_record": { "type": "boolean", "description": "When true, triggers background enrichment via data providers." }, "work_email": { "type": "string", "description": "Work email address." }, "personal_email": { "type": "string", "description": "Personal email address." }, "mobile_phone": { "type": "string", "description": "Mobile phone number." }, "work_phone": { "type": "string", "description": "Work phone number." }, "job_id": { "type": "string", "description": "Job UUID to add this person to that job pipeline as a candidate (creates the candidacy). Get IDs from POST /v1/jobs/search." }, "sourced_by": { "type": "string", "format": "uuid", "description": "UUID of the team member who sourced this candidate, recorded as \"Sourced by\" on the candidacy created by `job_id`. Get IDs from GET /v1/team-members. Requires `job_id`. Only applies to API-key requests; requests made as a signed-in user (session or OAuth, including MCP) always credit that user. If the person is already a candidate on the job, the existing sourcer is kept." }, "do_not_contact": { "type": "boolean", "description": "Set to true to mark this person as do-not-contact, or false to clear the flag." }, "do_not_contact_reason": { "type": "string", "description": "Free-text reason for the do-not-contact flag (e.g. \"Requested removal from outreach\"). Only meaningful when do_not_contact is true. When omitted, any existing reason is preserved." }, "do_not_contact_expiration_date": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when do-not-contact should automatically expire. Only meaningful when do_not_contact is true. Pass an explicit date to set a custom expiration, or null for an indefinite do-not-contact. When omitted on a new do-not-contact flag, the flag is indefinite. When omitted on an existing do-not-contact flag, the current expiration is preserved." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "string", "format": "uuid", "description": "Custom attribute definition UUID. Get from GET /v1/custom-fields/persons." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "null" } ], "description": "For scalar types (text, number, date, url, boolean): the value to set, or null to clear. For single-select: pass the tag NAME (e.g. \"Remote\", \"On-site\") or the tag option UUID from GET /v1/custom-fields/persons. A new tag is auto-created only for a name that does not exist yet; an unknown UUID is ignored. Null to clear." }, "add_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to add for multi-select fields. Pass tag NAMES (e.g. [\"Engineer\", \"Designer\"]) or tag option UUIDs from GET /v1/custom-fields/persons. A new tag is auto-created only for a name that does not exist yet; an unknown UUID is ignored. Duplicates silently skipped." }, "remove_values": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs." }, "add_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to add for multi-team-member fields. Get IDs from GET /v1/team-members." }, "remove_team_member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to remove for multi-team-member fields." }, "add_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to add for multi-company fields. Get IDs from POST /v1/companies/search." }, "remove_company_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Company UUIDs to remove for multi-company fields." }, "clear_all": { "type": "boolean", "description": "When true, removes all existing values for this multi-select, multi-team-member, or multi-company attribute. Combine with add_values/add_team_member_ids/add_company_ids to replace all values in one call." } }, "required": [ "attribute_id" ] }, "description": "Custom field values to update. Each attribute_id should appear once. Get attribute definitions from GET /v1/custom-fields/persons. For select fields, pass the tag NAME (e.g. \"Remote\") or the tag option UUID returned in that definition." } } }, "UpdatePersonResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "success", "data" ] }, "PersonCompensationCreateRequest": { "type": "object", "properties": { "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated job UUID, if this compensation is specific to a job candidacy." }, "current_compensation_base": { "type": [ "number", "null" ], "minimum": 0, "description": "Base salary amount." }, "current_compensation_bonus": { "type": [ "number", "null" ], "minimum": 0, "description": "Bonus cash amount. Ignored when bonus_percent is set, because the cash amount is calculated from base salary." }, "bonus_percent": { "type": [ "number", "null" ], "minimum": 0, "description": "Bonus as a percentage of base salary. When set, the cash bonus is calculated from base salary. Null clears the percent and keeps the bonus as a cash amount." }, "compensation_type": { "type": [ "string", "null" ], "enum": [ "desired", "actual", "minimum" ], "description": "Type of compensation: desired for expectations, actual for current or historical compensation, or minimum for a required floor." }, "currency_code": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\"). Defaults to USD when omitted." }, "equity_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Equity grant as a percentage." }, "equity_amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Equity grant as a fixed amount." }, "compensation_year": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 3000, "description": "The year this compensation applies to (e.g. 2025 for historical compensation)." }, "total_estimated_compensation": { "type": [ "number", "null" ], "minimum": 0, "description": "Total estimated annual compensation. When omitted, it is calculated as base salary + cash bonus + equity amount. On update, an omitted total is recalculated when those amounts change, unless the saved total was set to a different value." }, "note": { "type": [ "string", "null" ], "description": "Free-text notes about the compensation package, constraints, or preferences." } } }, "PersonCompensationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PersonCompensation" } }, "required": [ "success", "data" ] }, "PersonCompensationUpdateRequest": { "type": "object", "properties": { "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated job UUID, if this compensation is specific to a job candidacy." }, "current_compensation_base": { "type": [ "number", "null" ], "minimum": 0, "description": "Base salary amount." }, "current_compensation_bonus": { "type": [ "number", "null" ], "minimum": 0, "description": "Bonus cash amount. Ignored when bonus_percent is set, because the cash amount is calculated from base salary." }, "bonus_percent": { "type": [ "number", "null" ], "minimum": 0, "description": "Bonus as a percentage of base salary. When set, the cash bonus is calculated from base salary. Null clears the percent and keeps the bonus as a cash amount." }, "compensation_type": { "type": [ "string", "null" ], "enum": [ "desired", "actual", "minimum" ], "description": "Type of compensation: desired for expectations, actual for current or historical compensation, or minimum for a required floor." }, "currency_code": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\"). Defaults to USD when omitted." }, "equity_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Equity grant as a percentage." }, "equity_amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Equity grant as a fixed amount." }, "compensation_year": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 3000, "description": "The year this compensation applies to (e.g. 2025 for historical compensation)." }, "total_estimated_compensation": { "type": [ "number", "null" ], "minimum": 0, "description": "Total estimated annual compensation. When omitted, it is calculated as base salary + cash bonus + equity amount. On update, an omitted total is recalculated when those amounts change, unless the saved total was set to a different value." }, "note": { "type": [ "string", "null" ], "description": "Free-text notes about the compensation package, constraints, or preferences." } } }, "PersonCompensationDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "PersonActivitiesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "PersonDocumentsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonDocument" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "PersonDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique document UUID. Stable for the life of the document, and the same id returned when the document is uploaded. Use it as the key for syncing documents; do not use the file name or the signed link." }, "created_at": { "type": "string", "description": "ISO 8601 upload timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-modified timestamp." }, "type": { "type": "string", "description": "Document type (e.g. \"resume\", \"cover_letter\", \"other\")." }, "title": { "type": [ "string", "null" ], "description": "File name or document title." }, "link": { "type": "string", "description": "Short-lived signed download URL. Expires in minutes; re-fetch if needed." }, "text_content": { "type": [ "string", "null" ], "description": "Extracted plain-text content of the document. Only present when include_text=true was passed. May be truncated if the document exceeds the per-entry character cap." }, "char_count": { "type": "number", "description": "Number of characters in the returned text_content. Only present when include_text=true." }, "truncated": { "type": "boolean", "description": "True if text_content was trimmed due to character limits. Only present when include_text=true." } }, "required": [ "id", "created_at", "updated_at", "type", "title", "link" ] }, "DocumentUploadMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload. Allowed types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB." }, "title": { "type": "string", "description": "Document title. Defaults to the original filename if omitted." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values include resume_doc, resume_link, cover_letter, reference, additional_links, transcript, work_sample, offer_letter, assessment, and other. Teams may add custom values." }, "visible_in_share_links": { "type": "boolean", "description": "Whether to show this document in candidate share links. Defaults to false." } }, "required": [ "file", "type" ] }, "DocumentUploadRequest": { "type": "object", "properties": { "file_url": { "type": "string", "format": "uri", "description": "Publicly accessible HTTPS URL of a file to download and store. The server fetches the file, validates its type and size (max 25 MB), and stores it." }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Document title or filename (e.g. \"John_Doe_Resume.pdf\"). Defaults to the downloaded filename." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Team document type key. Seeded values include resume_doc, resume_link, cover_letter, reference, additional_links, transcript, work_sample, offer_letter, assessment, and other. Teams may add custom values." }, "visible_in_share_links": { "type": "boolean", "default": false, "description": "Whether to show this document in candidate share links." } }, "required": [ "file_url", "type" ] }, "DocumentUploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Created document UUID." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "type": { "type": "string", "description": "Document type." }, "title": { "type": [ "string", "null" ], "description": "Document title." }, "link": { "type": "string", "description": "Signed download URL. Empty if external-only." }, "visible_in_share_links": { "type": "boolean", "description": "Whether visible in share links." } }, "required": [ "id", "created_at", "updated_at", "type", "title", "link", "visible_in_share_links" ] } }, "required": [ "success", "data" ] }, "PersonDocumentTypesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonDocumentType" } } }, "required": [ "success", "data" ] }, "PersonDocumentType": { "type": "object", "properties": { "type": { "type": "string", "description": "Type key. Use in document_types when filtering POST /v1/persons/search or GET /v1/persons/{id}/documents." }, "name": { "type": "string", "description": "Display name shown in the app (e.g. \"Resume\")." } }, "required": [ "type", "name" ] }, "SetPreferredEmailsBulkRequest": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID. Get IDs from POST /v1/persons/search." }, "email": { "type": "string", "minLength": 1, "description": "Email address to star as preferred. Must already exist on that person." } }, "required": [ "person_id", "email" ] }, "minItems": 1, "maxItems": 100, "description": "Persons to update (1–100). Invalid rows fail individually and do not block other rows. When the same person_id appears twice, the last entry wins." } }, "required": [ "updates" ] }, "SetPreferredEmailsBulkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SetPreferredEmailsBulkResult" } }, "required": [ "success", "data" ] }, "SetPreferredEmailsBulkResult": { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "preferred_email": { "type": "string" } }, "required": [ "person_id", "preferred_email" ] }, "description": "Persons whose preferred email was set. preferred_email is the stored address that was starred." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID that failed." }, "error": { "type": "string", "description": "Why this row was not updated, such as \"Person not found\" or \"Email is not stored on this person\"." } }, "required": [ "person_id", "error" ] }, "description": "Rows that could not be updated. Other valid rows in the same request are still processed." } }, "required": [ "updated", "failed" ] }, "SetPreferredPhonesBulkRequest": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID. Get IDs from POST /v1/persons/search." }, "phone": { "type": "string", "minLength": 1, "description": "Phone number to star as preferred. Must already exist on that person." } }, "required": [ "person_id", "phone" ] }, "minItems": 1, "maxItems": 100, "description": "Persons to update (1–100). Invalid rows fail individually and do not block other rows. When the same person_id appears twice, the last entry wins." } }, "required": [ "updates" ] }, "SetPreferredPhonesBulkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SetPreferredPhonesBulkResult" } }, "required": [ "success", "data" ] }, "SetPreferredPhonesBulkResult": { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "preferred_phone": { "type": "string" } }, "required": [ "person_id", "preferred_phone" ] }, "description": "Persons whose preferred phone was set. preferred_phone is the stored number that was starred." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID that failed." }, "error": { "type": "string", "description": "Why this row was not updated, such as \"Person not found\" or \"Email is not stored on this person\"." } }, "required": [ "person_id", "error" ] }, "description": "Rows that could not be updated. Other valid rows in the same request are still processed." } }, "required": [ "updated", "failed" ] }, "SetEmailsBouncedBulkRequest": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID. Get IDs from POST /v1/persons/search." }, "email": { "type": "string", "minLength": 1, "description": "Email address to mark or unmark. Must already exist on that person. Matching ignores letter case." }, "is_bounced": { "type": "boolean", "description": "true marks the address as bounced, so emails and campaigns skip it. false clears the bounced mark." } }, "required": [ "person_id", "email", "is_bounced" ] }, "minItems": 1, "maxItems": 100, "description": "Email addresses to mark or unmark (1–100). Several addresses of the same person can be sent in one request. Invalid rows fail individually and do not block other rows. When the same person_id and email appear twice, the last entry wins." } }, "required": [ "updates" ] }, "SetEmailsBouncedBulkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SetEmailsBouncedBulkResult" } }, "required": [ "success", "data" ] }, "SetEmailsBouncedBulkResult": { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "is_bounced": { "type": "boolean" } }, "required": [ "person_id", "email", "is_bounced" ] }, "description": "Addresses now in the requested state. email is the stored address; is_bounced is its bounced state after the request." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID of the row that failed." }, "email": { "type": "string", "description": "Email address from the failed row." }, "error": { "type": "string", "description": "Why this row was not applied, such as \"Person not found\" or \"Email is not stored on this person\"." } }, "required": [ "person_id", "email", "error" ] }, "description": "Rows that could not be updated. Other valid rows in the same request are still processed." } }, "required": [ "updated", "failed" ] }, "DeleteEmailsBulkRequest": { "type": "object", "properties": { "deletions": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID. Get IDs from POST /v1/persons/search." }, "email": { "type": "string", "minLength": 1, "description": "Email address to remove. Must already exist on that person. Matching ignores letter case." } }, "required": [ "person_id", "email" ] }, "minItems": 1, "maxItems": 100, "description": "Email addresses to remove (1–100). Several addresses of the same person can be sent in one request. Invalid rows fail individually and do not block other rows." } }, "required": [ "deletions" ] }, "DeleteEmailsBulkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DeleteEmailsBulkResult" } }, "required": [ "success", "data" ] }, "DeleteEmailsBulkResult": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } }, "required": [ "person_id", "email" ] }, "description": "Addresses that were removed. email is the stored address that was deleted." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID of the row that failed." }, "email": { "type": "string", "description": "Email address from the failed row." }, "error": { "type": "string", "description": "Why this row was not applied, such as \"Person not found\" or \"Email is not stored on this person\"." } }, "required": [ "person_id", "email", "error" ] }, "description": "Rows that could not be removed. Other valid rows in the same request are still processed." } }, "required": [ "deleted", "failed" ] }, "SetPreferredEmailRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "Email address to star as preferred. Must already exist on this person." } }, "required": [ "email" ] }, "SetPreferredPhoneRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 1, "description": "Phone number to star as preferred. Must already exist on this person. Formatting differences are accepted when the digits match." } }, "required": [ "phone" ] }, "PersonContactEnrichmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PersonContactEnrichmentData" } }, "required": [ "success", "data" ] }, "PersonContactEnrichmentData": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid" }, "linkedin_public_id": { "type": "string" }, "linkedin_url": { "type": "string", "format": "uri" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Enriched email address or phone number." }, "contact_data_type": { "type": "string", "enum": [ "personal", "work", "mobile", "home" ], "description": "Contact classification." }, "source": { "type": "string", "description": "Provider or cache source that returned this value." }, "priority": { "type": "integer", "description": "Lower numbers are higher priority." } }, "required": [ "value", "contact_data_type", "source", "priority" ] } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Enriched email address or phone number." }, "contact_data_type": { "type": "string", "enum": [ "personal", "work", "mobile", "home" ], "description": "Contact classification." }, "source": { "type": "string", "description": "Provider or cache source that returned this value." }, "priority": { "type": "integer", "description": "Lower numbers are higher priority." } }, "required": [ "value", "contact_data_type", "source", "priority" ] }, "description": "Phone numbers when reveal_phone_numbers is enabled for the organization; otherwise empty." }, "quota": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "used": { "type": "integer", "description": "Enrichment requests used by this organization in the current UTC month." }, "limit": { "type": "integer", "description": "Monthly organization enrichment limit: 500 × active team members with an auth_user_id." }, "remaining": { "type": "integer" }, "billable_member_count": { "type": "integer", "description": "Count of distinct active team members with an auth_user_id used to compute the limit." }, "per_member_limit": { "type": "integer", "description": "Per-member monthly allowance (currently 500)." }, "period_start": { "type": "string", "description": "UTC calendar month start (YYYY-MM-DD)." }, "resets_at": { "type": "string", "description": "ISO timestamp when the monthly quota resets (1st of next month, UTC)." } }, "required": [ "allowed", "used", "limit", "remaining", "billable_member_count", "per_member_limit", "period_start", "resets_at" ] } }, "required": [ "person_id", "linkedin_public_id", "linkedin_url", "emails", "phones", "quota" ] }, "RetainerPacksListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RetainerPack" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "RetainerPack": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Retainer pack UUID." }, "organization_company_id": { "type": "string", "format": "uuid", "description": "Client company the pack belongs to." }, "organization_company_name": { "type": [ "string", "null" ], "description": "Client company name." }, "name": { "type": "string", "description": "Pack name." }, "currency_code": { "type": "string", "description": "ISO 4217 currency code." }, "invoice_number": { "type": [ "string", "null" ], "description": "Invoice number of the pack." }, "link_extra_hires": { "type": "boolean", "description": "Whether hires after the last claimed retainer still link to the pack at 0." }, "firm_commission_percent": { "type": "number", "description": "Percent of each open retainer the firm keeps." }, "is_closed": { "type": "boolean", "description": "Closed packs are no longer offered when logging placements." }, "closed_at": { "type": [ "string", "null" ], "description": "ISO 8601 time the pack was closed." }, "fee_status": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Fee status UUID." }, "name": { "type": "string", "description": "Status name (e.g. \"Paid\")." }, "status_type": { "type": "string", "enum": [ "pending", "invoiced", "paid", "cancelled" ], "description": "Lifecycle category of the status: `pending`, `invoiced`, `paid` or `cancelled`. Revenue reports count `paid` fees as collected." }, "color": { "type": "string", "description": "Hex color code of the status badge." } }, "required": [ "id", "name", "status_type", "color" ], "description": "Status of the pack invoice, shared by every retainer." }, "expected_date": { "type": [ "string", "null" ], "format": "date", "description": "Invoice date." }, "actual_payment_date": { "type": [ "string", "null" ], "format": "date", "description": "Date the pack was marked paid." }, "amount_each": { "type": "number", "description": "Amount of each open retainer (the pack's current per-retainer amount)." }, "default_split": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Credited team member UUID." }, "team_member_name": { "type": [ "string", "null" ], "description": "Team member full name." }, "role": { "type": [ "string", "null" ], "description": "Why this person is credited, if set." }, "split_percentage": { "type": "number", "description": "Share of the credit in percent." } }, "required": [ "team_member_id", "team_member_name", "role", "split_percentage" ] }, "description": "The pack's retainer split, used by its open retainers." }, "retainers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Retainer UUID." }, "position": { "type": "number", "description": "1-based position for display (#1, #2, ...)." }, "amount": { "type": "number", "description": "Retainer amount in the pack currency." }, "firm_commission_percent": { "type": "number", "description": "Percent of this retainer the firm keeps." }, "claim": { "oneOf": [ { "type": "object", "properties": { "is_restricted": { "type": "boolean", "enum": [ false ], "description": "The placement is visible to you." }, "placement_fee_event_id": { "type": "string", "format": "uuid", "description": "Placement UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job the placement was logged on." }, "job_title": { "type": "string", "description": "Job title." }, "candidate_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Candidate record (the person on that job)." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Placed person UUID." }, "person_name": { "type": [ "string", "null" ], "description": "Placed person name." }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Placement start date." } }, "required": [ "is_restricted", "placement_fee_event_id", "job_id", "job_title", "candidate_id", "person_id", "person_name", "start_date" ] }, { "type": "object", "properties": { "is_restricted": { "type": "boolean", "enum": [ true ], "description": "The placement is on a confidential job you cannot see; only its ID is returned." }, "placement_fee_event_id": { "type": "string", "format": "uuid", "description": "Placement UUID." } }, "required": [ "is_restricted", "placement_fee_event_id" ] }, { "type": "null" } ], "description": "The placement that used this retainer, or null while it is open." }, "splits": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Credited team member UUID." }, "team_member_name": { "type": [ "string", "null" ], "description": "Team member full name." }, "role": { "type": [ "string", "null" ], "description": "Why this person is credited, if set." }, "split_percentage": { "type": "number", "description": "Share of the credit in percent." }, "split_amount": { "type": "number", "description": "This person's credit for the retainer, after the firm commission." } }, "required": [ "team_member_id", "team_member_name", "role", "split_percentage", "split_amount" ] }, "description": "Credit for this retainer. Open retainers follow the pack's split; claimed ones keep the split they were claimed with." } }, "required": [ "id", "position", "amount", "firm_commission_percent", "claim", "splits" ] }, "description": "Every retainer in the pack, in order." }, "extra_hires": { "type": "array", "items": { "type": "object", "properties": { "placement_fee_event_id": { "type": "string", "format": "uuid", "description": "Placement UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Job the placement was logged on." }, "job_title": { "type": "string", "description": "Job title." }, "candidate_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Candidate record (the person on that job)." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Placed person UUID." }, "person_name": { "type": [ "string", "null" ], "description": "Placed person name." }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Placement start date." } }, "required": [ "placement_fee_event_id", "job_id", "job_title", "candidate_id", "person_id", "person_name", "start_date" ], "description": "A placement linked to the pack after every paid retainer was claimed, at a 0 retainer and billed the full fee." }, "description": "Placements linked to the pack at a 0 retainer." }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Adjustment UUID." }, "amount": { "type": "number", "description": "Money returned, stored positive." }, "comment": { "type": [ "string", "null" ], "description": "Note on the adjustment." }, "adjusted_on": { "type": "string", "format": "date", "description": "Date of the adjustment." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." } }, "required": [ "id", "amount", "comment", "adjusted_on", "created_at" ] }, "description": "Refunds and other money returned on the pack, oldest first." }, "summary": { "type": "object", "properties": { "retainer_count": { "type": "number", "description": "Number of retainers in the pack." }, "claimed_count": { "type": "number", "description": "Retainers used by a placement." }, "open_count": { "type": "number", "description": "Retainers not used yet." }, "extra_hire_count": { "type": "number", "description": "Placements linked after every retainer was claimed." }, "total_amount": { "type": "number", "description": "Sum of every retainer amount." }, "remaining_amount": { "type": "number", "description": "Sum of the open retainer amounts." }, "adjustments_total": { "type": "number", "description": "Sum of the adjustments." }, "net_retained": { "type": "number", "description": "Total amount minus adjustments." } }, "required": [ "retainer_count", "claimed_count", "open_count", "extra_hire_count", "total_amount", "remaining_amount", "adjustments_total", "net_retained" ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last update timestamp." } }, "required": [ "id", "organization_company_id", "organization_company_name", "name", "currency_code", "invoice_number", "link_extra_hires", "firm_commission_percent", "is_closed", "closed_at", "fee_status", "expected_date", "actual_payment_date", "amount_each", "default_split", "retainers", "extra_hires", "adjustments", "summary", "created_at", "updated_at" ] }, "CreateRetainerPackBody": { "type": "object", "properties": { "organization_company_id": { "type": "string", "format": "uuid", "description": "Client company the pack is sold to. The company must be marked as a client." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Pack name shown on the company page, 1 to 200 characters (e.g. \"Q4 2026 GTM pack\")." }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code of every retainer in the pack (e.g. USD). Can't change once a retainer is claimed." }, "invoice_number": { "type": [ "string", "null" ], "description": "Invoice number for the whole pack (one invoice per pack), at most 100 characters. Send null on update to clear it." }, "fee_status_id": { "type": "string", "format": "uuid", "description": "Status of the pack invoice, shared by every retainer in the pack. Get IDs from GET /v1/fee-statuses. Only admins can move a paid pack back to an unpaid status." }, "expected_date": { "type": [ "string", "null" ], "format": "date", "description": "Invoice date (YYYY-MM-DD), shared by every retainer in the pack. Send null on update to clear it." }, "link_extra_hires": { "type": "boolean", "description": "When every paid retainer is claimed, new hires at this client still link to the pack with a 0 retainer and are billed the full fee. Defaults to true." }, "firm_commission_percent": { "type": "number", "description": "Percent of each open retainer the firm keeps before team credit is split, 0 to 100. Defaults to 0." }, "retainer_count": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of retainers in the pack, 1 to 100. To top up an existing pack, send add_retainers instead. Lowering it removes open retainers from the end and can't go below the claimed retainers." }, "amount_each": { "type": "number", "description": "Amount of each retainer, 0 or more. A change applies to open retainers; claimed retainers keep their amount." }, "default_split": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member to credit. Get IDs from GET /v1/team-members." }, "role": { "type": [ "string", "null" ], "description": "Optional label for why this person is credited (e.g. \"Sales\")." }, "split_percentage": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Share of the retainer credit, above 0 and at most 100." } }, "required": [ "team_member_id", "split_percentage" ] }, "description": "Who gets credit for each retainer. Send an empty list for no split, otherwise the percentages must total 100. Credit per retainer is the retainer amount minus the firm commission, times each person's percentage. Applies to open retainers; a claimed retainer keeps the split it was claimed with. Only admins can change the split of a paid pack. Defaults to an empty list." } }, "required": [ "organization_company_id", "name", "currency_code", "fee_status_id", "retainer_count", "amount_each" ] }, "RetainerPackResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/RetainerPack" } }, "required": [ "success", "data" ] }, "UpdateRetainerPackBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Pack name shown on the company page, 1 to 200 characters (e.g. \"Q4 2026 GTM pack\")." }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code of every retainer in the pack (e.g. USD). Can't change once a retainer is claimed." }, "invoice_number": { "type": [ "string", "null" ], "description": "Invoice number for the whole pack (one invoice per pack), at most 100 characters. Send null on update to clear it." }, "fee_status_id": { "type": "string", "format": "uuid", "description": "Status of the pack invoice, shared by every retainer in the pack. Get IDs from GET /v1/fee-statuses. Only admins can move a paid pack back to an unpaid status." }, "expected_date": { "type": [ "string", "null" ], "format": "date", "description": "Invoice date (YYYY-MM-DD), shared by every retainer in the pack. Send null on update to clear it." }, "link_extra_hires": { "type": "boolean", "description": "When every paid retainer is claimed, new hires at this client still link to the pack with a 0 retainer and are billed the full fee. Defaults to true." }, "firm_commission_percent": { "type": "number", "description": "Percent of each open retainer the firm keeps before team credit is split, 0 to 100. Defaults to 0." }, "retainer_count": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of retainers in the pack, 1 to 100. To top up an existing pack, send add_retainers instead. Lowering it removes open retainers from the end and can't go below the claimed retainers." }, "amount_each": { "type": "number", "description": "Amount of each retainer, 0 or more. A change applies to open retainers; claimed retainers keep their amount." }, "default_split": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member to credit. Get IDs from GET /v1/team-members." }, "role": { "type": [ "string", "null" ], "description": "Optional label for why this person is credited (e.g. \"Sales\")." }, "split_percentage": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Share of the retainer credit, above 0 and at most 100." } }, "required": [ "team_member_id", "split_percentage" ] }, "description": "Who gets credit for each retainer. Send an empty list for no split, otherwise the percentages must total 100. Credit per retainer is the retainer amount minus the firm commission, times each person's percentage. Applies to open retainers; a claimed retainer keeps the split it was claimed with. Only admins can change the split of a paid pack. Defaults to an empty list." }, "add_retainers": { "type": "integer", "minimum": 1, "description": "Top-up: number of open retainers to add to the pack (same invoice), added to the pack's current count. Use instead of retainer_count." } } }, "CloseRetainerPackBody": { "type": "object", "properties": { "refund_amount": { "type": "number", "description": "Money returned to the client for unclaimed retainers. Recorded as an adjustment on the pack; at most the net retained amount." }, "refund_comment": { "type": [ "string", "null" ], "maxLength": 500, "description": "Note on the refund, at most 500 characters." }, "refund_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the refund (YYYY-MM-DD). Defaults to today." } } }, "CreateRetainerPackAdjustmentBody": { "type": "object", "properties": { "amount": { "type": "number", "description": "Money returned on the pack, above 0 and at most the net retained amount. Stored positive and shown as a negative line." }, "comment": { "type": [ "string", "null" ], "maxLength": 500, "description": "Note on the adjustment, at most 500 characters." }, "adjusted_on": { "type": [ "string", "null" ], "format": "date", "description": "Date of the adjustment (YYYY-MM-DD). Defaults to today." } }, "required": [ "amount" ] }, "ReplacePackRetainerSplitBody": { "type": "object", "properties": { "splits": { "type": "array", "items": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member to credit. Get IDs from GET /v1/team-members." }, "role": { "type": [ "string", "null" ], "description": "Optional label for why this person is credited (e.g. \"Sales\")." }, "split_percentage": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Share of the retainer credit, above 0 and at most 100." } }, "required": [ "team_member_id", "split_percentage" ] }, "description": "Who gets credit for each retainer. Send an empty list for no split, otherwise the percentages must total 100. Credit per retainer is the retainer amount minus the firm commission, times each person's percentage." } }, "required": [ "splits" ] }, "ScorecardTemplatesSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Case-insensitive substring match on template name or description." }, "job_id": { "type": "string", "format": "uuid", "description": "Return only templates scoped to this job UUID. Pair with include_org_wide to also include org-wide templates." }, "include_org_wide": { "type": "boolean", "default": false, "description": "When true and job_id is provided, also return org-wide (job_id IS NULL) templates. Defaults to false." }, "created_by_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter by creator team member UUIDs. Get IDs from GET /v1/team-members." }, "is_archived": { "type": "boolean", "default": false, "description": "Filter by archived status. Defaults to false (active templates only)." }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at", "name" ], "default": "created_at", "description": "Column to sort by. One of: created_at (default), updated_at, name." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc." } } }, "ScorecardTemplatesSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardTemplate" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "ScorecardTemplate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scorecard template UUID." }, "name": { "type": "string", "description": "Template name shown to raters." }, "description": { "type": [ "string", "null" ], "description": "Optional template description." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this template is scoped to. Null for org-wide templates. Only one active (non-archived) template can exist per job in the team." }, "rating_scale": { "type": "integer", "description": "Star rating scale. Must be one of: 3, 4, 5 (default), or 10." }, "enable_ai_auto_grade": { "type": "boolean", "description": "When true, the AI copilot can auto-grade candidates against this template." }, "is_archived": { "type": "boolean", "description": "Archived templates are hidden from selection." }, "overall_default_text": { "type": [ "string", "null" ], "description": "Default note text pre-filled in the overall summary section when raters score with this template." }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/ScorecardCreator" }, { "type": [ "object", "null" ], "description": "Team member who created the template." } ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardTemplateCriterion" }, "description": "Criteria attached to the template, sorted by position ascending. Includes archived criteria (use is_archived to filter)." } }, "required": [ "id", "name", "description", "job_id", "rating_scale", "enable_ai_auto_grade", "is_archived", "overall_default_text", "created_by", "created_at", "updated_at", "criteria" ] }, "ScorecardCreator": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ] }, "ScorecardTemplateCriterion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Criterion UUID." }, "name": { "type": "string", "description": "Criterion display name." }, "description": { "type": [ "string", "null" ], "description": "Optional longer description shown to raters." }, "importance": { "type": "string", "enum": [ "must_have", "nice_to_have" ], "description": "Weighting: must_have or nice_to_have." }, "position": { "type": "number", "description": "Sort order. Lower values are displayed first." }, "is_archived": { "type": "boolean", "description": "Archived criteria are hidden from the UI." }, "default_text": { "type": [ "string", "null" ], "description": "Default note text pre-filled when raters open this criterion." } }, "required": [ "id", "name", "description", "importance", "position", "is_archived", "default_text" ] }, "ScorecardTemplateByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ScorecardTemplate" } }, "required": [ "success", "data" ] }, "ScorecardTemplateUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Template name shown to raters." }, "description": { "type": [ "string", "null" ], "description": "Optional template description. Pass null to clear." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID to scope the template to. The job must belong to this team. Pass null to make org-wide. Only one active template can exist per job in the team." }, "rating_scale": { "type": "integer", "description": "Star rating scale. Must be one of: 3, 4, 5, or 10." }, "enable_ai_auto_grade": { "type": "boolean", "description": "Toggle AI auto-grading for this template." }, "is_archived": { "type": "boolean", "description": "Archive or unarchive the template." }, "overall_default_text": { "type": [ "string", "null" ], "description": "Default overall summary text. Plain text only. Pass null to clear." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to record as last_updated_by. Ignored for session and OAuth callers (the authenticated member is always recorded). Required for API-key auth, which has no implicit member context." }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Criterion display name (required)." }, "description": { "type": "string", "description": "Optional longer description shown to raters." }, "importance": { "type": "string", "enum": [ "must_have", "nice_to_have" ], "default": "nice_to_have", "description": "Weighting. Defaults to nice_to_have." }, "position": { "type": "number", "description": "Sort order. When omitted, criteria are positioned in the order provided (1, 2, 3, …)." }, "default_text": { "type": "string", "description": "Default note text pre-filled when raters open this criterion." } }, "required": [ "name" ] }, "description": "When provided, REPLACES the active criteria set: existing non-archived criteria are archived (preserving historical ratings) and these new criteria are inserted. Omit to leave criteria unchanged." } } }, "ScorecardTemplateUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ScorecardTemplate" } }, "required": [ "success", "data" ] }, "ScorecardTemplateCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Template name shown to raters (required)." }, "description": { "type": "string", "description": "Optional template description." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID to scope this template to. The job must belong to this team. Only one active template can exist per job in the team. Omit to create an org-wide template." }, "rating_scale": { "type": "integer", "default": 5, "description": "Star rating scale. Must be one of: 3, 4, 5 (default), or 10." }, "enable_ai_auto_grade": { "type": "boolean", "default": false, "description": "When true, the AI copilot can auto-grade candidates against this template. Defaults to false." }, "overall_default_text": { "type": "string", "description": "Default note text pre-filled in the overall summary section. Plain text only." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to record as the template creator. Ignored for session and OAuth callers (the authenticated member is always recorded). Required for API-key auth, which has no implicit member context." }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Criterion display name (required)." }, "description": { "type": "string", "description": "Optional longer description shown to raters." }, "importance": { "type": "string", "enum": [ "must_have", "nice_to_have" ], "default": "nice_to_have", "description": "Weighting. Defaults to nice_to_have." }, "position": { "type": "number", "description": "Sort order. When omitted, criteria are positioned in the order provided (1, 2, 3, …)." }, "default_text": { "type": "string", "description": "Default note text pre-filled when raters open this criterion." } }, "required": [ "name" ] }, "description": "Criteria to attach to the template. Each criterion has a name and optional description, importance, position, and default_text. When position is omitted, criteria are numbered in the order provided." } }, "required": [ "name" ] }, "ScorecardTemplateCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ScorecardTemplate" } }, "required": [ "success", "data" ] }, "ScorecardsSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "person_id": { "type": "string", "format": "uuid", "description": "Return only scorecards for this person UUID." }, "job_id": { "type": "string", "format": "uuid", "description": "Return only scorecards scoped to this job UUID." }, "candidate_id": { "type": "string", "format": "uuid", "description": "Return only scorecards for this candidate UUID." }, "template_id": { "type": "string", "format": "uuid", "description": "Return only scorecards created from this template UUID." }, "created_by_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter by creator team member UUIDs. Get IDs from GET /v1/team-members." }, "is_starred": { "type": "boolean", "description": "Filter by starred status." }, "is_draft": { "type": "boolean", "description": "Filter by draft status. Pass true for incomplete drafts only, false for published scorecards only." }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at", "overall_rating" ], "default": "created_at", "description": "Column to sort by. One of: created_at (default), updated_at, overall_rating." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc." } } }, "ScorecardsSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Scorecard" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "Scorecard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scorecard UUID." }, "person_id": { "type": "string", "format": "uuid", "description": "Person UUID being evaluated." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID this scorecard is scoped to, or null for a person-level scorecard." }, "candidate_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Candidate UUID (person+job) — auto-resolved when job_id is set and the person is a candidate on that job." }, "assessment_template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Scorecard template UUID used to score." }, "template": { "allOf": [ { "$ref": "#/components/schemas/ScorecardTemplateRef" }, { "type": [ "object", "null" ], "description": "Embedded template summary." } ] }, "job": { "allOf": [ { "$ref": "#/components/schemas/ScorecardJobRef" }, { "type": [ "object", "null" ], "description": "Embedded job summary (when job_id is set)." } ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/ScorecardSubmissionCreator" }, { "type": [ "object", "null" ], "description": "Team member who created the scorecard." } ] }, "overall_rating": { "type": [ "number", "null" ], "description": "Overall numeric score (0 to template rating_scale). Null when only criterion-level ratings or a note were left." }, "overall_comment": { "type": [ "string", "null" ], "description": "Plain-text overall summary note. Null when not provided." }, "is_starred": { "type": "boolean", "description": "Whether this scorecard is starred (highlighted as the primary scorecard)." }, "is_draft": { "type": "boolean", "description": "Whether this scorecard is an incomplete draft. Drafts can be resumed later and are excluded from people-list averages and client share links." }, "visible_in_client_share_link": { "type": "boolean", "description": "Whether this scorecard is included on the client share link for the linked job." }, "criterion_ratings": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardCriterionRating" }, "description": "Per-criterion ratings and comments, sorted by criterion position." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." } }, "required": [ "id", "person_id", "job_id", "candidate_id", "assessment_template_id", "template", "job", "created_by", "overall_rating", "overall_comment", "is_starred", "is_draft", "visible_in_client_share_link", "criterion_ratings", "created_at", "updated_at" ] }, "ScorecardTemplateRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scorecard template UUID." }, "name": { "type": "string", "description": "Template name." }, "rating_scale": { "type": "integer", "description": "Template rating scale (3, 4, 5, or 10)." } }, "required": [ "id", "name", "rating_scale" ] }, "ScorecardJobRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "title": { "type": "string", "description": "Job title." }, "company_name": { "type": [ "string", "null" ], "description": "Company name attached to the job." } }, "required": [ "id", "title", "company_name" ] }, "ScorecardSubmissionCreator": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ] }, "ScorecardCriterionRating": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Criterion rating UUID." }, "criterion_id": { "type": "string", "format": "uuid", "description": "Assessment template criterion UUID." }, "criterion_name": { "type": [ "string", "null" ], "description": "Display name of the criterion." }, "importance": { "type": [ "string", "null" ], "enum": [ "must_have", "nice_to_have" ], "description": "Criterion importance weighting." }, "position": { "type": [ "number", "null" ], "description": "Display position of the criterion." }, "rating": { "type": [ "number", "null" ], "description": "Numeric score (0 to rating_scale). Null when only a comment was left." }, "comment": { "type": [ "string", "null" ], "description": "Plain-text comment for this criterion. Null when no comment was left." } }, "required": [ "id", "criterion_id", "criterion_name", "importance", "position", "rating", "comment" ] }, "ScorecardByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Scorecard" } }, "required": [ "success", "data" ] }, "ScorecardUpdateRequest": { "type": "object", "properties": { "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Job UUID to scope this scorecard to. Pass null to clear. When changed, candidate_id is auto-resolved from the new (person_id, job_id) pair." }, "overall_rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Overall score (0 to template rating_scale). Pass null to clear." }, "overall_comment": { "type": [ "string", "null" ], "description": "Plain-text overall summary note. Pass null to clear." }, "is_starred": { "type": "boolean", "description": "Toggle the starred flag." }, "is_draft": { "type": "boolean", "description": "Set true to keep this scorecard as an incomplete draft, or false to publish it. Drafts are excluded from people-list averages and client share links." }, "visible_in_client_share_link": { "type": "boolean", "description": "Toggle client share link visibility. Only effective when a job_id is set on the scorecard and is_draft is false." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to record as last_updated_by. Ignored for session and OAuth callers (the authenticated member is always recorded). Required for API-key auth, which has no implicit member context." }, "criterion_ratings": { "type": "array", "items": { "type": "object", "properties": { "criterion_id": { "type": "string", "format": "uuid", "description": "Criterion UUID from the template (assessment_template_criteria.id)." }, "rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Numeric score from 0 to the template rating_scale (max 10). At least one of rating or comment must be set." }, "comment": { "type": [ "string", "null" ], "description": "Plain-text comment for this criterion. Pass null or omit to leave only a numeric rating." } }, "required": [ "criterion_id" ] }, "description": "When provided, REPLACES all criterion ratings on this scorecard. Pass an empty array to clear all criterion ratings." } } }, "ScorecardUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Scorecard" } }, "required": [ "success", "data" ] }, "ScorecardCreateRequest": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Person UUID being evaluated (required)." }, "assessment_template_id": { "type": "string", "format": "uuid", "description": "Scorecard template UUID used to score the person (required)." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID to scope this scorecard to. When set, the candidate_id is auto-resolved from the (person_id, job_id) candidate record." }, "overall_rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Overall score (0 to template rating_scale). Optional — leave null to score only at the criterion level." }, "overall_comment": { "type": "string", "description": "Plain-text overall summary note." }, "is_starred": { "type": "boolean", "default": false, "description": "Whether to mark this scorecard as starred. Defaults to false." }, "is_draft": { "type": "boolean", "default": false, "description": "Whether to save this scorecard as an incomplete draft. Drafts are excluded from people-list averages and client share links. Defaults to false." }, "visible_in_client_share_link": { "type": "boolean", "default": false, "description": "Whether to expose this scorecard on the client share link for the linked job. Only respected when job_id is set and is_draft is false. Defaults to false." }, "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID to record as the scorecard creator. Ignored for session and OAuth callers (the authenticated member is always recorded). Required for API-key auth, which has no implicit member context." }, "criterion_ratings": { "type": "array", "items": { "type": "object", "properties": { "criterion_id": { "type": "string", "format": "uuid", "description": "Criterion UUID from the template (assessment_template_criteria.id)." }, "rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Numeric score from 0 to the template rating_scale (max 10). At least one of rating or comment must be set." }, "comment": { "type": [ "string", "null" ], "description": "Plain-text comment for this criterion. Pass null or omit to leave only a numeric rating." } }, "required": [ "criterion_id" ] }, "description": "Per-criterion ratings and comments. Each entry must reference a criterion_id belonging to the assessment_template_id and must include a rating, a comment, or both." } }, "required": [ "person_id", "assessment_template_id" ] }, "ScorecardCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Scorecard" } }, "required": [ "success", "data" ] }, "TasksSearchBody": { "type": "object", "properties": { "offset": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Full-text search on task content. Uses PostgreSQL tsvector index for efficient matching." }, "task_types": { "type": "array", "items": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ] }, "description": "Filter by one or more task types." }, "related_to": { "type": "string", "format": "uuid", "description": "UUID of the related entity (person, deal, client, or job). Must be paired with related_record_type." }, "related_record_type": { "type": "string", "enum": [ "person", "deal", "client", "job" ], "description": "Type of the related entity. Must be paired with related_to." }, "is_completed": { "type": "boolean", "description": "Filter by completion status. Open tasks for people who have left a campaign are omitted by default; completed ones still appear." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter by assigned team member UUIDs. Returns tasks owned by any of these members. Get IDs from GET /v1/team-members." }, "due_date_start": { "type": "string", "description": "ISO 8601 date — only include tasks due on or after this date. Tasks with no due date are excluded." }, "due_date_end": { "type": "string", "description": "ISO 8601 date — only include tasks due on or before this date. Tasks with no due date are excluded." }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at", "due_date" ], "default": "created_at", "description": "Column to sort by. One of: created_at (default), updated_at, due_date." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc." } } }, "TasksSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "Task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Task UUID." }, "content_text": { "type": [ "string", "null" ], "description": "Plain text content of the task." }, "task_type": { "type": "string", "description": "Task type: text, linkedin_message, linkedin_connection, call, other." }, "due_date": { "type": [ "string", "null" ], "description": "ISO 8601 due date." }, "is_completed": { "type": "boolean", "description": "Whether the task is completed." }, "person_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Related person UUID." }, "deal_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Related deal UUID." }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Related client (organization_companies) UUID." }, "job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Related job UUID." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-updated timestamp." }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/TaskOwner" }, "description": "Team members assigned to this task." } }, "required": [ "id", "content_text", "task_type", "due_date", "is_completed", "person_id", "deal_id", "client_id", "job_id", "created_at", "updated_at", "owners" ] }, "TaskOwner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team member UUID." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." } }, "required": [ "id", "first_name", "last_name" ] }, "TaskByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "success", "data" ] }, "TaskUpdateRequest": { "type": "object", "properties": { "content_text": { "type": "string", "minLength": 1, "description": "Plain text content of the task." }, "task_type": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ], "description": "Task type." }, "due_date": { "type": [ "string", "null" ], "description": "ISO 8601 due date, or null to clear." }, "is_completed": { "type": "boolean", "description": "Whether the task is completed." } } }, "TaskUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "success", "data" ] }, "TaskCreateRequest": { "type": "object", "properties": { "content_text": { "type": "string", "minLength": 1, "description": "Plain text content of the task (required)." }, "task_type": { "type": "string", "enum": [ "text", "linkedin_message", "linkedin_connection", "call", "other" ], "description": "Task type (required): text, linkedin_message, linkedin_connection, call, other." }, "due_date": { "type": "string", "description": "ISO 8601 due date." }, "is_completed": { "type": "boolean", "default": false, "description": "Whether the task is completed. Defaults to false." }, "person_id": { "type": "string", "format": "uuid", "description": "Person UUID to associate with this task." }, "deal_id": { "type": "string", "format": "uuid", "description": "Deal UUID to associate with this task." }, "client_id": { "type": "string", "format": "uuid", "description": "Client (organization_companies) UUID to associate with this task." }, "job_id": { "type": "string", "format": "uuid", "description": "Job UUID to associate with this task." }, "owner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Team member UUIDs to assign as task owners. Get IDs from GET /v1/team-members. When omitted or empty, the authenticated team member is assigned; API-key requests without a team member create an ownerless task." } }, "required": [ "content_text", "task_type" ] }, "TaskCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "success", "data" ] }, "TeamCapacityReportResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TeamCapacityReport" } }, "required": [ "success", "data" ] }, "TeamCapacityReport": { "type": "object", "properties": { "generated_at": { "type": "string", "description": "When the report was computed (ISO 8601)." }, "quarter_start": { "type": "string", "description": "Start of the current calendar quarter in UTC, used for the quarter metrics." }, "year_start": { "type": "string", "description": "Start of the current calendar year in UTC, used for `ytd_avg_fill_days`." }, "is_configured": { "type": "boolean", "description": "Whether an admin has saved board settings. When false, `settings` holds the defaults." }, "settings": { "$ref": "#/components/schemas/TeamCapacitySettings" }, "summary": { "type": "object", "properties": { "member_count": { "type": "integer", "description": "Active team members in the report." }, "active_search_count": { "type": "integer", "description": "Unique active jobs after the status filter, across the whole team." }, "team_avg_load_score": { "type": "number", "description": "Average load score across members with a load score above zero." } }, "required": [ "member_count", "active_search_count", "team_avg_load_score" ], "description": "Team-wide totals." }, "available_roles": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityRole" }, "description": "Roles held on active jobs. Use these names for `role_filter`, `role_weights`, and role sort columns." }, "available_job_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityJobStatus" }, "description": "The team’s job statuses in pipeline order. Use these names for `job_status_filter`." }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityMember" }, "description": "One row per active team member, ordered by `settings.sort`. Members with no value for the sort column come last." } }, "required": [ "generated_at", "quarter_start", "year_start", "is_configured", "settings", "summary", "available_roles", "available_job_statuses", "members" ] }, "TeamCapacitySettings": { "type": "object", "properties": { "show_search_stage": { "type": "boolean", "description": "Whether the board shows the search stage columns." }, "stage_config": { "$ref": "#/components/schemas/TeamCapacityStageConfig" }, "show_load_score": { "type": "boolean", "description": "Whether the board shows the weighted load score column." }, "role_weights": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityRoleWeight" }, "description": "Load score weight for each role. Roles without a saved weight get a default: the owner role gets more weight and the remaining roles share the rest." }, "enable_active_search_color_coding": { "type": "boolean", "description": "Whether member names are colored light, moderate, or heavy by active search count." }, "active_search_color_thresholds": { "$ref": "#/components/schemas/TeamCapacityColorThresholds" }, "job_status_filter": { "type": "array", "items": { "type": "string" }, "description": "Job status names included in the report. Empty means every status. Until an admin saves settings, this defaults to every status that is not closed won or closed lost." }, "role_filter": { "type": "array", "items": { "type": "string" }, "description": "Role names included in the report. A member’s search only counts when they hold one of these roles on it. Empty means every role." }, "sort": { "$ref": "#/components/schemas/TeamCapacitySort" } }, "required": [ "show_search_stage", "stage_config", "show_load_score", "role_weights", "enable_active_search_color_coding", "active_search_color_thresholds", "job_status_filter", "role_filter", "sort" ] }, "TeamCapacityStageConfig": { "type": "object", "properties": { "stage_1_name": { "type": "string", "description": "Display name for the first stage (newest searches)." }, "stage_1_max_weeks": { "type": "integer", "description": "Searches kicked off up to this many weeks ago fall in stage 1." }, "stage_2_name": { "type": "string", "description": "Display name for the second stage." }, "stage_2_max_weeks": { "type": "integer", "description": "Searches older than stage 1 and up to this many weeks old fall in stage 2. Always greater than `stage_1_max_weeks`." }, "stage_3_name": { "type": "string", "description": "Display name for the third stage. Holds every active search older than `stage_2_max_weeks`." } }, "required": [ "stage_1_name", "stage_1_max_weeks", "stage_2_name", "stage_2_max_weeks", "stage_3_name" ] }, "TeamCapacityRoleWeight": { "type": "object", "properties": { "role_name": { "type": "string", "description": "Job team role name." }, "weight": { "type": "integer", "description": "Points a member earns toward their load score for each active search where they hold this role." } }, "required": [ "role_name", "weight" ] }, "TeamCapacityColorThresholds": { "type": "object", "properties": { "moderate_min": { "type": "integer", "description": "Members with at least this many active searches are shown as moderate (yellow)." }, "heavy_min": { "type": "integer", "description": "Members with at least this many active searches are shown as heavy (red). Always greater than `moderate_min`." } }, "required": [ "moderate_min", "heavy_min" ] }, "TeamCapacitySort": { "type": "object", "properties": { "column": { "type": "string", "description": "Column the board is sorted by. One of `member`, `title`, `total_searches`, `stage_1`, `stage_2`, `stage_3`, `load_score`, `kicked_off_this_quarter`, `closed_this_quarter`, `avg_days_out`, `avg_days_left`, `ytd_avg_fill_days`, or a role name to sort by that role’s column in the Role Breakdown." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction." } }, "required": [ "column", "direction" ] }, "TeamCapacityRole": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name." }, "is_owner_role": { "type": "boolean", "description": "Whether this is the job owner role." } }, "required": [ "name", "is_owner_role" ] }, "TeamCapacityJobStatus": { "type": "object", "properties": { "name": { "type": "string", "description": "Job status name." }, "color": { "type": [ "string", "null" ], "description": "Status color (hex)." }, "status_type": { "type": [ "string", "null" ], "description": "Status category, such as `in_progress`, `closed_won`, or `closed_lost`." } }, "required": [ "name", "color", "status_type" ] }, "TeamCapacityMember": { "type": "object", "properties": { "team_member_id": { "type": "string", "format": "uuid", "description": "Team member UUID. Matches IDs from `GET /v1/team-members`." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "title": { "type": [ "string", "null" ], "description": "Team member title, such as Partner or Associate." }, "image_url": { "type": [ "string", "null" ], "description": "Avatar URL." }, "total_searches": { "type": "integer", "description": "Active (not archived) jobs the member is on, after the status and role filters." }, "workload_tier": { "type": "string", "enum": [ "light", "moderate", "heavy" ], "description": "Workload tier from `total_searches` and `settings.active_search_color_thresholds`." }, "stage_breakdown": { "$ref": "#/components/schemas/TeamCapacityStageBreakdown" }, "role_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityRoleCount" }, "description": "Active searches per role, for the roles the member holds. A member with two roles on one job counts once under each role." }, "load_score": { "type": "number", "description": "Sum of role weights across every role the member holds on every active search." }, "kicked_off_this_quarter": { "type": "integer", "description": "Jobs the member is on with an open date between the start of the quarter and now." }, "closed_this_quarter": { "type": "integer", "description": "Jobs the member is on with a closed status and an end date between the start of the quarter and now." }, "avg_days_out": { "type": [ "number", "null" ], "description": "Average days since open date across active searches. Null when none have an open date." }, "avg_days_left": { "type": [ "number", "null" ], "description": "Average days until end date across active searches. Negative values mean overdue. Null when none have an end date." }, "ytd_avg_fill_days": { "type": [ "number", "null" ], "description": "Average days from open to end date for archived jobs that ended this year. Null when there are none." }, "active_searches": { "type": "array", "items": { "$ref": "#/components/schemas/TeamCapacityActiveSearch" }, "description": "Active searches, newest kickoff first." } }, "required": [ "team_member_id", "first_name", "last_name", "title", "image_url", "total_searches", "workload_tier", "stage_breakdown", "role_breakdown", "load_score", "kicked_off_this_quarter", "closed_this_quarter", "avg_days_out", "avg_days_left", "ytd_avg_fill_days", "active_searches" ] }, "TeamCapacityStageBreakdown": { "type": "object", "properties": { "stage_1": { "type": "integer", "description": "Active searches in stage 1 (see `settings.stage_config`)." }, "stage_2": { "type": "integer", "description": "Active searches in stage 2." }, "stage_3": { "type": "integer", "description": "Active searches in stage 3." } }, "required": [ "stage_1", "stage_2", "stage_3" ] }, "TeamCapacityRoleCount": { "type": "object", "properties": { "role_name": { "type": "string", "description": "Job team role name." }, "active_searches": { "type": "integer", "description": "Active searches where the member holds this role." } }, "required": [ "role_name", "active_searches" ] }, "TeamCapacityActiveSearch": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Job UUID." }, "title": { "type": "string", "description": "Job title." }, "company_name": { "type": "string", "description": "Client company name, or `Unknown` when the job has none." }, "company_domain": { "type": [ "string", "null" ], "description": "Client company domain, without protocol or `www.`." }, "open_date": { "type": [ "string", "null" ], "description": "Date the search was kicked off." }, "end_date": { "type": [ "string", "null" ], "description": "Target or actual end date of the search." }, "role_names": { "type": "array", "items": { "type": "string" }, "description": "Roles the member holds on this job." } }, "required": [ "job_id", "title", "company_name", "company_domain", "open_date", "end_date", "role_names" ] }, "TeamCapacitySettingsUpdate": { "type": "object", "properties": { "show_search_stage": { "type": "boolean", "description": "Show or hide the search stage columns." }, "stage_config": { "type": "object", "properties": { "stage_1_name": { "type": "string", "minLength": 1, "maxLength": 40 }, "stage_1_max_weeks": { "type": "integer", "minimum": 1, "maximum": 51 }, "stage_2_name": { "type": "string", "minLength": 1, "maxLength": 40 }, "stage_2_max_weeks": { "type": "integer", "minimum": 2, "maximum": 52 }, "stage_3_name": { "type": "string", "minLength": 1, "maxLength": 40 } }, "description": "Stage names and week limits. Fields you leave out keep their current value. `stage_2_max_weeks` must stay greater than `stage_1_max_weeks`." }, "show_load_score": { "type": "boolean", "description": "Show or hide the load score column." }, "role_weights": { "type": "array", "items": { "type": "object", "properties": { "role_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Role name from `available_roles`." }, "weight": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999, "description": "New weight for this role. Pass null to go back to the default weight." } }, "required": [ "role_name", "weight" ] }, "maxItems": 100, "description": "Role weights to change. Roles you leave out keep their current weight." }, "enable_active_search_color_coding": { "type": "boolean", "description": "Turn workload color coding on member names on or off." }, "active_search_color_thresholds": { "type": "object", "properties": { "moderate_min": { "type": "integer", "minimum": 1, "maximum": 998 }, "heavy_min": { "type": "integer", "minimum": 2, "maximum": 999 } }, "description": "Workload thresholds. Fields you leave out keep their current value. `heavy_min` must stay greater than `moderate_min`." }, "job_status_filter": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100, "description": "Replaces the job status filter. Names must match `available_job_statuses`. Pass an empty array to include every status." }, "role_filter": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100, "description": "Replaces the role filter. Names must match the team’s job team roles. Pass an empty array to include every role." }, "sort": { "type": "object", "properties": { "column": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Column the board is sorted by. One of `member`, `title`, `total_searches`, `stage_1`, `stage_2`, `stage_3`, `load_score`, `kicked_off_this_quarter`, `closed_this_quarter`, `avg_days_out`, `avg_days_left`, `ytd_avg_fill_days`, or a role name to sort by that role’s column in the Role Breakdown." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`." } }, "required": [ "column" ], "description": "Default sort for the board." } } }, "TeamCapacitySettingsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TeamCapacitySettings" } }, "required": [ "success", "data" ] }, "TeamMembersListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Team member UUID. Use this ID in person_owner_ids, candidate_owner_ids, sourced_by_ids, and team_member_attribute_filters across search endpoints." }, "first_name": { "type": [ "string", "null" ], "description": "First name." }, "last_name": { "type": [ "string", "null" ], "description": "Last name." }, "email": { "type": [ "string", "null" ], "description": "Email address (from authentication provider)." }, "image_url": { "type": [ "string", "null" ], "description": "Profile image URL." }, "is_active": { "type": "boolean", "description": "True if the team member is currently active and can log in." } }, "required": [ "id", "first_name", "last_name", "email", "image_url", "is_active" ] }, "TeamMemberByIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TeamMember" } }, "required": [ "success", "data" ] } }, "parameters": {}, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authenticate with a Bearer token: API key, OAuth token, or session token." } } }, "paths": { "/v1/activity-reports": { "post": { "operationId": "generateActivityReport", "summary": "Generate an activity & stage-change report", "description": "Aggregates recruiter activity, candidate sourcing, pipeline stage changes, campaign enrollments, and tasks for the requested date window. Group by recruiter, job, or company. Mirrors the in-app \"Generate report\" surface and is the recommended way to produce daily / weekly / monthly performance reports.\n\nSession and OAuth callers need `org:reports:candidate_pipeline` (`org:admin` bypasses). `crm_activities` also needs `org:reports:crm`; without it that include is dropped. API keys are gated by `reports:read`.\n\n**Date filter**: applies to `created_at` for activities / candidates / tasks, `entered_at` for stage changes, and `enrolled_at` for campaign enrollments.\n\n**Optional sections** via `include`:\n- `pipeline_snapshot` — current candidate count per pipeline stage (job/company segments only).\n- `job_breakdown` — per-job candidates-sourced breakdown for each recruiter (team_member segments only).\n- `crm_activities` — fold `client_activities` + `client_status_changes` into the company segment metrics.", "tags": [ "Activity Reports" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityReportRequest" } } } }, "responses": { "200": { "description": "Activity report generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityReportResponse" }, "example": { "success": true, "data": { "segment_by": "team_member", "period": "weekly", "date_from": "2026-06-19T19:00:00Z", "date_to": "2026-06-26T19:00:00Z", "aggregate": { "activities_by_type": [ { "type": "campaign_enrollment", "label": "Campaign Enrollments", "count": 18 }, { "type": "secondary_note", "label": "Notes", "count": 12 }, { "type": "email", "label": "Emails", "count": 8 }, { "type": "linkedin_message", "label": "LinkedIn Messages", "count": 24 }, { "type": "call_note", "label": "Call Note", "count": 4 } ], "candidates_sourced": 42, "stage_changes": 21, "rejections": 6, "enrollments": 18, "tasks": 9, "stage_changes_by_stage": [ { "pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "stage_name": "Sourced", "stage_color": "#94a3b8", "global_order": 1, "count": 12 }, { "pipeline_stage_id": "678e9012-e34d-56f7-a890-123456789012", "stage_name": "Interview", "stage_color": "#facc15", "global_order": 3, "count": 9 } ], "pipeline_snapshot": [ { "pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "stage_name": "Sourced", "stage_color": "#94a3b8", "global_order": 1, "candidate_count": 30 }, { "pipeline_stage_id": "678e9012-e34d-56f7-a890-123456789012", "stage_name": "Interview", "stage_color": "#facc15", "global_order": 3, "candidate_count": 5 } ], "job_breakdown": [ { "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_title": "Senior Software Engineer", "company_id": "111e2222-e333-4444-e555-666666666666", "company_name": "Acme Corp", "candidates_sourced": 28 } ] }, "segments": [ { "segment_type": "team_member", "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith", "company_id": null, "company_name": null, "metrics": { "activities_by_type": [ { "type": "campaign_enrollment", "label": "Campaign Enrollments", "count": 18 }, { "type": "secondary_note", "label": "Notes", "count": 12 }, { "type": "email", "label": "Emails", "count": 8 }, { "type": "linkedin_message", "label": "LinkedIn Messages", "count": 24 }, { "type": "call_note", "label": "Call Note", "count": 4 } ], "candidates_sourced": 42, "stage_changes": 21, "rejections": 6, "enrollments": 18, "tasks": 9, "stage_changes_by_stage": [ { "pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "stage_name": "Sourced", "stage_color": "#94a3b8", "global_order": 1, "count": 12 }, { "pipeline_stage_id": "678e9012-e34d-56f7-a890-123456789012", "stage_name": "Interview", "stage_color": "#facc15", "global_order": 3, "count": 9 } ], "pipeline_snapshot": [ { "pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "stage_name": "Sourced", "stage_color": "#94a3b8", "global_order": 1, "candidate_count": 30 }, { "pipeline_stage_id": "678e9012-e34d-56f7-a890-123456789012", "stage_name": "Interview", "stage_color": "#facc15", "global_order": 3, "candidate_count": 5 } ], "job_breakdown": [ { "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_title": "Senior Software Engineer", "company_id": "111e2222-e333-4444-e555-666666666666", "company_name": "Acme Corp", "candidates_sourced": 28 } ] } } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/search": { "post": { "operationId": "searchAutomations", "summary": "Search automations", "description": "Search saved automations with pagination and sorting.\n\n**Filters**: `keywords` (name substring), `is_enabled`, `is_archived` (defaults to false), `trigger_type`.\n\n**Sorting**: `sort_by` — `created_at` (default), `updated_at`, `name`. `sort_order` — `asc` or `desc` (default).\n\nList rows include action counts, not the full trigger or action payloads. Use `GET /v1/automations/{id}` for the full recipe.", "tags": [ "Automations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsSearchBody" } } } }, "responses": { "200": { "description": "Automations found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsSearchResponse" }, "example": { "success": true, "data": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2222", "name": "Email owner when a candidate is rejected", "is_enabled": true, "is_archived": false, "runs_on_api_changes": false, "trigger_type": "candidate_status_changed", "action_count": 6, "action_types": [ "send_email", "delay", "add_note", "agent_instructions", "create_task" ], "created_at": "2026-08-21T10:00:00Z", "updated_at": "2026-08-21T10:00:00Z" } ], "meta": { "total": 12, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/trigger-types": { "get": { "operationId": "listAutomationTriggerTypes", "summary": "List automation trigger types", "description": "Returns the closed set of trigger types you can save on an automation.", "tags": [ "Automations" ], "responses": { "200": { "description": "Trigger types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationTriggerTypesResponse" }, "example": { "success": true, "data": [ { "value": "schedule", "label": "Schedule" }, { "value": "candidate_status_changed", "label": "Candidate status changed" }, { "value": "job_status_changed", "label": "Job status changed" }, { "value": "job_created", "label": "Job created" }, { "value": "deal_status_changed", "label": "Deal status changed" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/action-types": { "get": { "operationId": "listAutomationActionTypes", "summary": "List automation action types", "description": "Returns the closed set of action types you can attach to an automation.", "tags": [ "Automations" ], "responses": { "200": { "description": "Action types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationActionTypesResponse" }, "example": { "success": true, "data": [ { "value": "send_email", "label": "Send email" }, { "value": "add_note", "label": "Add note" }, { "value": "agent_instructions", "label": "Agent instructions" }, { "value": "delay", "label": "Delay" }, { "value": "create_task", "label": "Create task" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/run-statuses": { "get": { "operationId": "listAutomationRunStatuses", "summary": "List automation run statuses", "description": "Returns the closed set of statuses a run can be in.", "tags": [ "Automations" ], "responses": { "200": { "description": "Run statuses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunStatusesResponse" }, "example": { "success": true, "data": [ { "value": "pending", "label": "Pending" }, { "value": "processing", "label": "Processing" }, { "value": "waiting", "label": "Waiting" }, { "value": "completed", "label": "Completed" }, { "value": "failed", "label": "Failed" }, { "value": "skipped", "label": "Skipped" }, { "value": "dead_letter", "label": "Dead letter" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/{id}": { "get": { "operationId": "getAutomationById", "summary": "Get automation by ID", "description": "Retrieve one automation, including its trigger and ordered actions. Archived automations are still returned by ID.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Automation ID" } } ], "responses": { "200": { "description": "Automation found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationByIdResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2222", "name": "Email owner when a candidate is rejected", "is_enabled": true, "is_archived": false, "runs_on_api_changes": false, "created_by": "567e8901-e23c-45d6-e789-012345678901", "trigger": { "type": "candidate_status_changed", "pipeline_stage_ids": [ "123e4567-e89b-12d3-a456-426614174000" ], "match_rejection_stages": true }, "actions": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2223", "position": 1, "action_type": "send_email", "recipient_type": "candidate", "team_member_id": null, "payload": { "subject": "Your application for {{job_name}}", "body": "Hi {{candidate_first_name}},\n\nThank you for your time on the {{job_name}} search.\n\nBest,\n{{search_owner}}", "sender": { "kind": "mailbox", "nylas_grant_id": "8b3f4e5d-6c7a-4182-9c9d-0e1f2a3b4c5d" }, "include_signature": true } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2228", "position": 2, "action_type": "send_email", "recipient_type": "team_members", "team_member_id": null, "payload": { "subject": "{{candidate_name}} was rejected on {{job_name}}", "body": "{{candidate_name}} moved to {{stage_name}} on {{job_name}}.", "team_member_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "email_addresses": [ "finance@yourfirm.com" ] } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2226", "position": 3, "action_type": "delay", "payload": { "amount": 2, "unit": "days" } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2224", "position": 4, "action_type": "add_note", "team_member_id": "567e8901-e23c-45d6-e789-012345678901", "payload": { "content": "Rejected by automation — review before closing the loop." } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2225", "position": 5, "action_type": "agent_instructions", "payload": { "instructions": "Summarize why this candidate was rejected.", "allow_update_records": true, "allow_delete_records": false, "output_format": { "kind": "bullet_list" } } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2227", "position": 6, "action_type": "create_task", "assignee_type": "job_owner", "team_member_id": null, "payload": { "content": "Call {{candidate_name}} with feedback on {{job_name}}", "task_type": "call", "due_in_days": 1 } } ], "created_at": "2026-08-21T10:00:00Z", "updated_at": "2026-08-21T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateAutomation", "summary": "Update automation", "description": "Partially update an automation. `is_enabled` toggles new fires; already-claimed runs still finish. When `trigger` is sent, the schedule or status row is replaced. When `actions` is sent, the full action list is replaced. Emails from a mailbox and agent steps act as the automation's creator, so only the creator can edit an automation that emails candidates or client contacts from a mailbox or has an agent step; where agent steps are not turned on yet, only adding or changing an agent step, moving one onto a schedule or changing its schedule is limited to the creator. Other admins can still turn it off or archive it, and an admin who edits an automation whose creator left takes it over. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Automation ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpdateRequest" } } } }, "responses": { "200": { "description": "Automation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpdateResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2222", "name": "Email owner when a candidate is rejected", "is_enabled": true, "is_archived": false, "runs_on_api_changes": false, "created_by": "567e8901-e23c-45d6-e789-012345678901", "trigger": { "type": "candidate_status_changed", "pipeline_stage_ids": [ "123e4567-e89b-12d3-a456-426614174000" ], "match_rejection_stages": true }, "actions": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2223", "position": 1, "action_type": "send_email", "recipient_type": "candidate", "team_member_id": null, "payload": { "subject": "Your application for {{job_name}}", "body": "Hi {{candidate_first_name}},\n\nThank you for your time on the {{job_name}} search.\n\nBest,\n{{search_owner}}", "sender": { "kind": "mailbox", "nylas_grant_id": "8b3f4e5d-6c7a-4182-9c9d-0e1f2a3b4c5d" }, "include_signature": true } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2228", "position": 2, "action_type": "send_email", "recipient_type": "team_members", "team_member_id": null, "payload": { "subject": "{{candidate_name}} was rejected on {{job_name}}", "body": "{{candidate_name}} moved to {{stage_name}} on {{job_name}}.", "team_member_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "email_addresses": [ "finance@yourfirm.com" ] } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2226", "position": 3, "action_type": "delay", "payload": { "amount": 2, "unit": "days" } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2224", "position": 4, "action_type": "add_note", "team_member_id": "567e8901-e23c-45d6-e789-012345678901", "payload": { "content": "Rejected by automation — review before closing the loop." } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2225", "position": 5, "action_type": "agent_instructions", "payload": { "instructions": "Summarize why this candidate was rejected.", "allow_update_records": true, "allow_delete_records": false, "output_format": { "kind": "bullet_list" } } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2227", "position": 6, "action_type": "create_task", "assignee_type": "job_owner", "team_member_id": null, "payload": { "content": "Call {{candidate_name}} with feedback on {{job_name}}", "task_type": "call", "due_in_days": 1 } } ], "created_at": "2026-08-21T10:00:00Z", "updated_at": "2026-08-21T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Only the creator can edit an automation that sends from their mailbox or has an agent step, or the caller is not an admin", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "archiveAutomation", "summary": "Archive automation", "description": "Archives the automation and disables new fires. The recipe stays recoverable via `PATCH` with `is_archived: false`. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Automation ID" } } ], "responses": { "200": { "description": "Automation archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Automation archived successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Only organization admins can change automations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations": { "post": { "operationId": "createAutomation", "summary": "Create automation", "description": "Create an automation with exactly one trigger and one or more actions.\n\n`add_note` and `send_email` to a candidate are only valid when `trigger.type` is `candidate_status_changed`. Schedule `next_run_at` is computed from `rrule`, `dtstart`, and `timezone`. API keys can't create an automation that emails a candidate or client contacts from a mailbox (`payload.sender`), because it would send as a team member; set those up in the app. An `agent_instructions` action runs only on a `schedule` trigger, as the automation's creator, so in an automation created with an API key it is skipped. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta.", "tags": [ "Automations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCreateRequest" } } } }, "responses": { "201": { "description": "Automation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCreateResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3333", "name": "Monday offer follow-ups", "is_enabled": true, "is_archived": false, "runs_on_api_changes": false, "created_by": "567e8901-e23c-45d6-e789-012345678901", "trigger": { "type": "schedule", "rrule": "FREQ=WEEKLY;BYDAY=MO;BYHOUR=8;BYMINUTE=0", "dtstart": "2026-08-24T08:00:00", "timezone": "America/New_York", "next_run_at": "2026-08-31T12:00:00Z" }, "actions": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3334", "position": 1, "action_type": "agent_instructions", "payload": { "instructions": "Find candidates who have been in Offer for more than 7 days on open searches, move each to Follow up and add a note saying why. Example row: | Priya Raman | Senior Controller | 9 days |", "allow_update_records": true, "allow_delete_records": false, "output_format": { "kind": "custom", "text": "One table row per candidate, longest wait first" } } }, { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3335", "position": 2, "action_type": "send_email", "recipient_type": "team_members", "team_member_id": null, "payload": { "subject": "Offers waiting for a follow-up", "body": "These offers need a follow-up this week:\n\n{{agent_output}}", "team_member_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "include_signature": false } } ], "created_at": "2026-08-21T10:00:00Z", "updated_at": "2026-08-21T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Only organization admins can change automations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/{id}/runs/search": { "post": { "operationId": "searchAutomationRuns", "summary": "Search automation runs", "description": "Paginated run log for one automation. Does not include per-action steps; use `GET /v1/automations/runs/{runId}` for steps. Only organization admins, API keys and the automation's creator can see its runs.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Automation ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunsSearchBody" } } } }, "responses": { "200": { "description": "Runs found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunsSearchResponse" }, "example": { "success": true, "data": [ { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0011", "automation_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3333", "status": "waiting", "attempts": 0, "error_message": null, "trigger_type": "schedule", "trigger_payload": { "scheduled_for": "2026-08-31T12:00:00Z" }, "change_source": null, "candidate_id": null, "person_id": null, "job_id": null, "deal_id": null, "started_at": "2026-08-31T12:00:01Z", "finished_at": null, "resume_at": "2026-08-31T12:31:02Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:30:02Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0001", "automation_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee2222", "status": "waiting", "attempts": 0, "error_message": null, "trigger_type": "candidate_status_changed", "trigger_payload": { "candidate_id": "345e6789-e01b-23c4-d567-890123456789", "person_id": "456e7890-e12b-34d5-a678-901234567890", "job_id": "456e7890-e12b-34d5-a678-901234567890", "old_pipeline_stage_id": "123e4567-e89b-12d3-a456-426614174000", "new_pipeline_stage_id": "123e4567-e89b-12d3-a456-426614174000", "old_job_status_id": "234e5678-e90a-12b3-c456-789012345678", "new_job_status_id": "234e5678-e90a-12b3-c456-789012345678", "old_deal_status_id": "7a2e3d4c-5b6f-4071-8b8c-9d0e1f2a3b4c", "new_deal_status_id": "7a2e3d4c-5b6f-4071-8b8c-9d0e1f2a3b4c", "job_status_id": "234e5678-e90a-12b3-c456-789012345678", "organization_company_id": "678e9012-e34d-56e7-f890-123456789012", "scheduled_for": "2026-08-21T10:05:00Z" }, "change_source": "api", "candidate_id": "345e6789-e01b-23c4-d567-890123456789", "person_id": "456e7890-e12b-34d5-a678-901234567890", "job_id": "456e7890-e12b-34d5-a678-901234567890", "deal_id": "6f1d2c3b-4a5e-4f60-9a7b-8c9d0e1f2a3b", "started_at": "2026-08-21T10:05:00Z", "finished_at": null, "resume_at": "2026-08-23T10:05:01Z", "created_at": "2026-08-21T10:05:00Z", "updated_at": "2026-08-21T10:05:01Z" } ], "meta": { "total": 4, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Only admins and the automation's creator can see its runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/automations/runs/{runId}": { "get": { "operationId": "getAutomationRunById", "summary": "Get automation run by ID", "description": "Retrieve one run and its per-action steps. Only organization admins, API keys and the automation's creator can see its runs.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "description": "Run ID" } } ], "responses": { "200": { "description": "Run found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunByIdResponse" }, "example": { "success": true, "data": { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0011", "automation_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3333", "status": "waiting", "attempts": 0, "error_message": null, "trigger_type": "schedule", "trigger_payload": { "scheduled_for": "2026-08-31T12:00:00Z" }, "change_source": null, "candidate_id": null, "person_id": null, "job_id": null, "deal_id": null, "started_at": "2026-08-31T12:00:01Z", "finished_at": null, "resume_at": "2026-08-31T12:31:02Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:30:02Z", "steps": [ { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0012", "position": 1, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3334", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3334", "position": 1, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "Find candidates who have been in Offer for more than 7 days on open searches, move each to Follow up and add a note saying why. Example row: | Priya Raman | Senior Controller | 9 days |", "allow_update_records": true, "allow_delete_records": false, "output_format": { "kind": "custom", "text": "One table row per candidate, longest wait first" } } }, "status": "completed", "attempt": 1, "error_message": null, "result": { "code": "agent_completed", "agent_output": "Checked 14 candidates in Offer on open searches; 1 has waited more than 7 days.\n\n| Candidate | Search | Days in Offer |\n|---|---|---|\n| [Priya Raman](/projects/456e7890-e12b-34d5-a678-901234567890?personId=456e7890-e12b-34d5-a678-901234567890) | Senior Controller | 9 |", "agent_thread_id": "ccc33333-dddd-eeee-ffff-000000000001", "agent_changes": [ { "tool": "update-candidate-stage", "record": { "type": "candidate", "id": "345e6789-e01b-23c4-d567-890123456789" }, "fields": [ { "name": "stage_id", "value": "123e4567-e89b-12d3-a456-426614174000" } ], "status": "succeeded" }, { "tool": "create-person-activity", "record": null, "fields": [ { "name": "activity_type", "value": "note" }, { "name": "content_text", "value": "In Offer for 9 days with no reply; nudged the client." } ], "status": "failed", "reason": "Person not found" } ], "agent_change_totals": [ { "tool": "update-candidate-stage", "succeeded": 1, "failed": 0 }, { "tool": "create-person-activity", "succeeded": 0, "failed": 1 } ] }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:01:12Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:01:12Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0013", "position": 2, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3335", "action_type": "send_email", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3335", "position": 2, "action_type": "send_email", "recipient_type": "team_members", "team_member_id": null, "payload": { "subject": "Offers waiting for a follow-up", "body": "These offers need a follow-up this week:\n\n{{agent_output}}", "team_member_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "include_signature": false } }, "status": "completed", "attempt": 1, "error_message": null, "result": { "code": "email_sent", "message": "Sent to 1 of 2", "deliveries": [ { "to_email": "maya@kestrelpartners.com", "status": "sent" }, { "to_email": "sam@kestrelpartners.com", "status": "skipped", "reason": "An earlier attempt may already have sent this email, so it was not sent again." } ] }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:01:14Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:01:14Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0014", "position": 3, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3336", "action_type": "create_task", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3336", "position": 3, "action_type": "create_task", "recipient_type": null, "team_member_id": "567e8901-e23c-45d6-e789-012345678901", "payload": { "content": "Review the offers waiting for a follow-up", "task_type": "other", "due_in_days": 1 } }, "status": "completed", "attempt": 1, "error_message": null, "result": { "code": "task_created", "due_at": "2026-09-01T12:01:15Z" }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:01:15Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:01:15Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0015", "position": 4, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3337", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3337", "position": 4, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "Archive deals with no activity for 90 days.", "allow_update_records": true, "allow_delete_records": true, "output_format": { "kind": "bullet_list" } } }, "status": "skipped", "attempt": 1, "error_message": "This automation has no creator for the agent to act as, because it was created with an API key. Create it in the app instead.", "result": { "code": "agent_skipped" }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:01:15Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:01:15Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0016", "position": 5, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3338", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3338", "position": 5, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "List the five candidates added this week with the strongest sales background.", "allow_update_records": false, "allow_delete_records": false, "output_format": { "kind": "short_summary" } } }, "status": "skipped", "attempt": 1, "error_message": null, "result": { "code": "not_implemented", "message": "Agent steps are not turned on for this workspace." }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:01:15Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:01:15Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0017", "position": 6, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3339", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3339", "position": 6, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "Add a task for every open search without a task due this week.", "allow_update_records": true, "allow_delete_records": false, "output_format": { "kind": "table" } } }, "status": "failed", "attempt": 1, "error_message": "The agent ran into a problem or ran out of time before it finished.", "result": { "agent_thread_id": "ccc33333-dddd-eeee-ffff-000000000003", "agent_changes": [ { "tool": "create-task", "record": { "type": "task", "id": "ddd44444-eeee-ffff-0000-111111114444" }, "fields": [ { "name": "content_text", "value": "Call Priya about her offer" }, { "name": "task_type", "value": "text" }, { "name": "due_date", "value": "2026-09-01" }, { "name": "owner_ids", "value": [ "567e8901-e23c-45d6-e789-012345678901" ] } ], "status": "succeeded" } ], "agent_change_totals": [ { "tool": "create-task", "succeeded": 1, "failed": 0 } ] }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:02:58Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:02:58Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0018", "position": 7, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3340", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3340", "position": 7, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "Summarize this week's new client contacts by company.", "allow_update_records": false, "allow_delete_records": false, "output_format": null } }, "status": "waiting", "attempt": 1, "error_message": null, "result": { "code": "agent_running", "message": "The agent is working on it.", "resume_at": "2026-08-31T12:31:02Z", "agent_thread_id": "ccc33333-dddd-eeee-ffff-000000000002" }, "started_at": "2026-08-31T12:00:01Z", "finished_at": null, "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:30:02Z" }, { "id": "bbb22222-cccc-dddd-eeee-ffffffffffff0019", "position": 8, "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3341", "action_type": "agent_instructions", "action_config": { "action_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee3341", "position": 8, "action_type": "agent_instructions", "recipient_type": null, "team_member_id": null, "payload": { "instructions": "List open searches with no candidate added in the last 14 days.", "allow_update_records": false, "allow_delete_records": false, "output_format": { "kind": "bullet_list" } } }, "status": "failed", "attempt": 1, "error_message": "The agent did not start within 30 minutes.", "result": { "agent_thread_id": "ccc33333-dddd-eeee-ffff-000000000004" }, "started_at": "2026-08-31T12:00:01Z", "finished_at": "2026-08-31T12:30:02Z", "created_at": "2026-08-31T12:00:00Z", "updated_at": "2026-08-31T12:30:02Z" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Only admins and the automation's creator can see its runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/calendar-meetings": { "get": { "operationId": "listCalendarMeetings", "summary": "List calendar meetings", "description": "Retrieve a paginated list of calendar meetings tracked by the notetaker.\n\n**Filters**: `start_time_after` / `start_time_before` (ISO 8601 date range), `bot_status` (e.g. completed, failed, recording), `meeting_title` (case-insensitive text search).\n\n**Sorting**: `sort_by` (start_time, created_at) with `sort_order` (asc/desc, default desc).\n\n**Pagination**: Use `offset` and `limit` query params (max 100 per page).", "tags": [ "Calendar Meetings" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Return meetings starting at or after this timestamp (ISO 8601). Example: `2026-04-01T00:00:00Z`." }, "required": false, "name": "start_time_after", "in": "query" }, { "schema": { "type": "string", "description": "Return meetings starting at or before this timestamp (ISO 8601). Example: `2026-04-30T23:59:59Z`." }, "required": false, "name": "start_time_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "scheduled", "joining", "waiting_room", "in_call", "recording", "completed", "failed", "cancelled" ], "description": "Filter by notetaker bot status. Common values: `completed` (finished recording), `failed` (bot encountered an error), `recording` (currently in progress)." }, "required": false, "name": "bot_status", "in": "query" }, { "schema": { "type": "string", "description": "Case-insensitive text search on meeting title. Example: `Weekly Sync` matches \"Weekly Engineering Sync\"." }, "required": false, "name": "meeting_title", "in": "query" }, { "schema": { "type": "string", "enum": [ "start_time", "created_at" ], "default": "start_time", "description": "Column to sort results by. Defaults to `start_time`.\n- `start_time` — when the meeting is scheduled\n- `created_at` — when the meeting was created in the system" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (newest first)." }, "required": false, "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "Calendar meetings fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarMeetingsListResponse" }, "example": { "success": true, "data": [ { "id": "6d7e8f90-1234-5678-9012-abcdef012345", "meeting_title": "Weekly Engineering Sync", "meeting_url": "https://meet.google.com/abc-defg-hij", "start_time": "2026-04-07T10:00:00.000Z", "bot_status": "completed", "bot_opt_out": false, "has_recording": true, "created_at": "2026-04-06T18:00:00.000Z", "updated_at": "2026-04-07T11:10:00.000Z" } ], "meta": { "total": 42, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/calendar-meetings/{id}": { "get": { "operationId": "getCalendarMeetingById", "summary": "Get calendar meeting by ID", "description": "Retrieve detailed information about a specific calendar meeting including all associated recordings and their processing status.", "tags": [ "Calendar Meetings" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Calendar meeting UUID" } } ], "responses": { "200": { "description": "Calendar meeting fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarMeetingByIdResponse" }, "example": { "success": true, "data": { "id": "6d7e8f90-1234-5678-9012-abcdef012345", "meeting_title": "Weekly Engineering Sync", "meeting_url": "https://meet.google.com/abc-defg-hij", "meeting_key": "abc-defg-hij", "start_time": "2026-04-07T10:00:00.000Z", "bot_status": "completed", "bot_opt_out": false, "recordings": [ { "id": "5c6d7e8f-9012-3456-7890-abcdef012345", "processing_status": "completed", "recording_duration_seconds": 3600, "has_transcript": true } ], "created_at": "2026-04-06T18:00:00.000Z", "updated_at": "2026-04-07T11:10:00.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/search": { "post": { "operationId": "searchCampaigns", "summary": "Search campaigns", "description": "Search campaigns by name, type, owner and archived state, with pagination and sorting. Rows include the step count; pass `include: [\"stats\"]` to add enrollment counts and reply, open and click rates to each one. Use `GET /v1/campaigns/{id}` for steps. Needs `campaigns:read`.\n\nSigned-in users need access to campaigns in their role. API keys need the campaigns permission named on each endpoint.", "tags": [ "Campaigns" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsSearchBody" }, "example": { "keywords": "backend", "include": [ "stats" ], "sort_by": "updated_at", "sort_order": "desc" } } } }, "responses": { "200": { "description": "Campaigns found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsSearchResponse" }, "example": { "success": true, "data": [ { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "is_archived": false, "created_by": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "step_count": 3, "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z", "enrollment_counts": { "total": 42, "running": 27, "awaiting_task": 2, "replied": 6, "meeting_booked": 3, "bounced": 1, "completed": 4, "stopped": 1 }, "engagement": { "responded": 9, "interested": 5, "neutral": 2, "not_interested": 2, "opened": 0, "clicked": 7, "reply_rate": 22, "open_rate": null, "click_rate": 17 } } ], "meta": { "total": 12, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/types": { "get": { "operationId": "listCampaignTypes", "summary": "List campaign types", "description": "The campaign types you can create. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Campaign types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignTypesResponse" }, "example": { "success": true, "data": [ { "value": "candidate", "label": "Candidate", "description": "Outreach to candidates for a job." }, { "value": "business_development", "label": "Business development", "description": "Outreach to potential clients. Enrolled people become client contacts." }, { "value": "candidate_nurture", "label": "Candidate nurture", "description": "Long-running check-ins with candidates. Does not stop on reply." }, { "value": "client_nurture", "label": "Client nurture", "description": "Long-running check-ins with clients. Enrolled people become client contacts." } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/variables": { "get": { "operationId": "listCampaignVariables", "summary": "List campaign variables", "description": "The `{{variables}}` campaign steps can use. `person` and `sender` values fill in automatically, `job` values come from the job chosen when enrolling, `manual` values are typed in for each enrollment. Any name not in this list also works as a manual variable. AI variables are written as `{{ai:name}}` and need a description in the step `ai_variables`. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Campaign variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignVariablesResponse" }, "example": { "success": true, "data": [ { "name": "first_name", "label": "First name", "kind": "person", "aliases": [ "firstname" ], "example": "John", "hint": null }, { "name": "sender_email", "label": "Sender email", "kind": "sender", "aliases": [ "from_email", "sender_email_address" ], "example": "you@example.com", "hint": "The mailbox you are sending from." }, { "name": "search_client", "label": "Search client company", "kind": "job", "aliases": [ "client_name", "company_client", "job_company", "client_company" ], "example": "Globex", "hint": "The company this search is for. Left empty when it is confidential." }, { "name": "personalization_line", "label": "Personalization line", "kind": "manual", "aliases": [], "example": "", "hint": null } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/mailboxes": { "get": { "operationId": "listCampaignMailboxes", "summary": "List sending mailboxes", "description": "Mailboxes a team member can send campaign emails from: their own and those shared with them, with each one's status, daily limit and emails sent today. API keys must pass `sender_team_member_id`; signed-in users get their own. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Whose mailboxes to list. Required with an API key. Signed-in users can only list their own, so it can be left out." }, "required": false, "description": "Whose mailboxes to list. Required with an API key. Signed-in users can only list their own, so it can be left out.", "name": "sender_team_member_id", "in": "query" } ], "responses": { "200": { "description": "Mailboxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignMailboxesResponse" }, "example": { "success": true, "data": [ { "email": "riya@acmetalent.com", "owner_name": "Riya Kapoor", "is_shared": false, "status": "ready", "daily_limit": 250, "sent_today": 38, "sending_timezone": "Europe/London", "available_at": null }, { "email": "outreach@acmetalent.com", "owner_name": "Sam Lee", "is_shared": true, "status": "daily_limit_reached", "daily_limit": 250, "sent_today": 250, "sending_timezone": "America/New_York", "available_at": "2026-10-14T04:00:00.000Z" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}": { "get": { "operationId": "getCampaignById", "summary": "Get campaign by ID", "description": "One campaign with its settings, ordered steps, the manual and AI variables it needs when enrolling people, how many people are in it by status, and its reply, open and click rates as shown on the campaign card. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Campaign found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" }, "example": { "success": true, "data": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "is_archived": false, "created_by": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "step_count": 3, "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z", "enable_sequence_automation": true, "stop_on_response": true, "send_on_weekends": false, "send_on_holidays": false, "link_tracking": true, "open_tracking": false, "include_unsubscribe_link": false, "steps": [ { "id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "

Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ], "attachments": [ { "file_name": "Monzo backend engineering role.pdf", "content_type": "application/pdf", "size_bytes": 184320 } ], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: {{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}}, following up on my note. {{custom}}

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call {{first_name}} if they opened but did not reply.
", "timezone": "Europe/London", "time_window_start": null, "time_window_end": null, "include_signature": false, "block_until_task_complete": true, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": null } ], "manual_variables": [ "personalization_line", "custom" ], "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently.", "step_ids": [ "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43" ] } ], "enrollment_counts": { "total": 42, "running": 27, "awaiting_task": 2, "replied": 6, "meeting_booked": 3, "bounced": 1, "completed": 4, "stopped": 1 }, "engagement": { "responded": 9, "interested": 5, "neutral": 2, "not_interested": 2, "opened": 0, "clicked": 7, "reply_rate": 22, "open_rate": null, "click_rate": 17 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateCampaign", "summary": "Update campaign", "description": "Change only the fields you send. Signed-in users must be admins to change `sequence_type` or `enable_sequence_automation`. Setting `is_archived` to true stops everyone still in the campaign and returns how many were stopped; sending it again finishes a stop that was interrupted. Archiving also needs `campaigns:enroll`, because it stops email. Unarchiving restarts nobody. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdateRequest" }, "example": { "is_archived": true } } } }, "responses": { "200": { "description": "Campaign updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdateResponse" }, "example": { "success": true, "data": { "campaign": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "is_archived": true, "created_by": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "step_count": 3, "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-24T15:02:00.000Z", "enable_sequence_automation": true, "stop_on_response": true, "send_on_weekends": false, "send_on_holidays": false, "link_tracking": true, "open_tracking": false, "include_unsubscribe_link": false, "steps": [ { "id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ], "attachments": [ { "file_name": "Monzo backend engineering role.pdf", "content_type": "application/pdf", "size_bytes": 184320 } ], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: {{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}}, following up on my note. {{custom}}

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call {{first_name}} if they opened but did not reply.
", "timezone": "Europe/London", "time_window_start": null, "time_window_end": null, "include_signature": false, "block_until_task_complete": true, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": null } ], "manual_variables": [ "personalization_line", "custom" ], "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently.", "step_ids": [ "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43" ] } ], "enrollment_counts": { "total": 42, "running": 0, "awaiting_task": 0, "replied": 6, "meeting_booked": 3, "bounced": 0, "completed": 4, "stopped": 29 }, "engagement": { "responded": 9, "interested": 5, "neutral": 2, "not_interested": 2, "opened": 0, "clicked": 7, "reply_rate": 21.4, "open_rate": null, "click_rate": 17 } }, "stopped_enrollment_count": 28 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns": { "post": { "operationId": "createCampaign", "summary": "Create campaign", "description": "Create a campaign and its steps in one request. Creating a campaign sends nothing.\n\n**Subjects**: only the first email step needs a subject. Later email steps reply in the same thread, so their subject is set to `Re: `.\n\n**Variables**: use names from `GET /v1/campaigns/variables`, your own manual names, or `{{ai:name}}` with a description in the step `ai_variables`.\n\n**Nurture campaigns** (`candidate_nurture`, `client_nurture`) keep going after a reply and never move people through a pipeline, so `stop_on_response` and `enable_sequence_automation` are always false for them.\n\n**Owner**: signed-in users own what they create. API keys can set `owner_team_member_id`; otherwise the admin who created the key owns it. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCreateRequest" }, "example": { "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "owner_team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "enable_sequence_automation": true, "stop_on_response": true, "link_tracking": true, "open_tracking": false, "steps": [ { "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ] }, { "type": "email", "send_after_days": 3, "body_html": "
Hi {{first_name}}, following up on my note. {{custom}}

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true }, { "type": "manual", "send_after_days": 2, "body_html": "
Call {{first_name}} if they opened but did not reply.
", "block_until_task_complete": true } ] } } } }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" }, "example": { "success": true, "data": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "is_archived": false, "created_by": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "step_count": 3, "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z", "enable_sequence_automation": true, "stop_on_response": true, "send_on_weekends": false, "send_on_holidays": false, "link_tracking": true, "open_tracking": false, "include_unsubscribe_link": false, "steps": [ { "id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: {{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}}, following up on my note. {{custom}}

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call {{first_name}} if they opened but did not reply.
", "timezone": "Europe/London", "time_window_start": null, "time_window_end": null, "include_signature": false, "block_until_task_complete": true, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": null } ], "manual_variables": [ "personalization_line", "custom" ], "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently.", "step_ids": [ "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43" ] } ], "enrollment_counts": { "total": 0, "running": 0, "awaiting_task": 0, "replied": 0, "meeting_booked": 0, "bounced": 0, "completed": 0, "stopped": 0 }, "engagement": { "responded": 0, "interested": 0, "neutral": 0, "not_interested": 0, "opened": 0, "clicked": 0, "reply_rate": null, "open_rate": null, "click_rate": null } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/steps": { "post": { "operationId": "addCampaignStep", "summary": "Add campaign step", "description": "Add a step to the end of the campaign. People already enrolled keep the steps they were enrolled with and will not get this one, which the `existing_enrollees_will_not_receive_this_step` warning tells you. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStepInput" }, "example": { "type": "email", "send_after_days": 4, "body_html": "
Hi {{first_name}}, closing the loop on this. Happy to share more whenever suits.

{{sender_first_name}}
", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true } } } }, "responses": { "201": { "description": "Step added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStepResponse" }, "example": { "success": true, "data": { "step": { "id": "2b7d9f1a-5c3e-4a8b-9d6f-0e2c4a6b8d31", "order": 4, "type": "email", "send_after_days": 4, "subject": "Re: {{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}}, closing the loop on this. Happy to share more whenever suits.

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [], "attachments": [], "created_at": "2026-10-14T09:02:00.000Z", "updated_at": "2026-10-14T09:02:00.000Z" }, "warnings": [ { "code": "existing_enrollees_will_not_receive_this_step", "message": "People already in this campaign keep their current steps and will not get this one. Only people enrolled from now on will." } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/steps/{step_id}": { "patch": { "operationId": "updateCampaignStep", "summary": "Update campaign step", "description": "Change only the fields you send. Type, subject, body and `send_after_days` are copied when someone is enrolled, so edits reach people enrolled afterwards; changing `type` keeps the body. Sending window, timezone, signature and `block_until_task_complete` are read when each step runs, so they also apply to people already enrolled; `applies_to_existing_enrollments` lists which of your changes do. Changing the first email subject also updates the `Re:` subject of later email steps. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Step ID." }, "required": true, "description": "Step ID.", "name": "step_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStepUpdateRequest" }, "example": { "time_window_start": "08:00" } } } }, "responses": { "200": { "description": "Step updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStepUpdateResponse" }, "example": { "success": true, "data": { "step": { "id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "08:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ], "attachments": [ { "file_name": "Monzo backend engineering role.pdf", "content_type": "application/pdf", "size_bytes": 184320 } ], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-14T08:30:00.000Z" }, "applies_to_existing_enrollments": [ "time_window_start" ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteCampaignStep", "summary": "Delete campaign step", "description": "Delete a step nobody has been enrolled into yet. Returns `409 STEP_IN_USE` once anyone has been enrolled in it, and `409 LAST_STEP` for the only step of a campaign. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Step ID." }, "required": true, "description": "Step ID.", "name": "step_id", "in": "path" } ], "responses": { "200": { "description": "Step deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Step deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "People are enrolled in this step, or it is the only step", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/steps/reorder": { "post": { "operationId": "reorderCampaignSteps", "summary": "Reorder campaign steps", "description": "Send every step id in the new order. Steps move with their own wait time and settings, so check `send_after_days` afterwards. People already enrolled keep the order they were enrolled with; people enrolled afterwards get the new order. A new first email becomes the thread subject for later emails. Needs `campaigns:write`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStepsReorderRequest" }, "example": { "step_ids": [ "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17" ] } } } }, "responses": { "200": { "description": "Steps reordered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" }, "example": { "success": true, "data": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo", "sequence_type": "candidate", "is_archived": false, "created_by": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "step_count": 3, "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-14T08:45:00.000Z", "enable_sequence_automation": true, "stop_on_response": true, "send_on_weekends": false, "send_on_holidays": false, "link_tracking": true, "open_tracking": false, "include_unsubscribe_link": false, "steps": [ { "id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "{{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}},

{{ai:opening_line}} I'm hiring a {{search_name}} at {{search_client}}. {{personalization_line}}

You can see the role here. Open to a chat?

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently." } ], "attachments": [ { "file_name": "Monzo backend engineering role.pdf", "content_type": "application/pdf", "size_bytes": 184320 } ], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" }, { "id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 2, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call {{first_name}} if they opened but did not reply.
", "timezone": "Europe/London", "time_window_start": null, "time_window_end": null, "include_signature": false, "block_until_task_complete": true, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": null }, { "id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 3, "type": "email", "send_after_days": 3, "subject": "Re: {{search_name}} role at {{search_client}}", "body_html": "
Hi {{first_name}}, following up on my note. {{custom}}

{{sender_first_name}}
", "timezone": "Europe/London", "time_window_start": "09:00", "time_window_end": "17:00", "include_signature": true, "block_until_task_complete": false, "ai_variables": [], "attachments": [], "created_at": "2026-10-13T10:15:00.000Z", "updated_at": "2026-10-13T10:15:00.000Z" } ], "manual_variables": [ "personalization_line", "custom" ], "ai_variables": [ { "name": "opening_line", "description": "One sentence on the most relevant thing they have built or led recently.", "step_ids": [ "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43" ] } ], "enrollment_counts": { "total": 42, "running": 27, "awaiting_task": 2, "replied": 6, "meeting_booked": 3, "bounced": 1, "completed": 4, "stopped": 1 }, "engagement": { "responded": 9, "interested": 5, "neutral": 2, "not_interested": 2, "opened": 0, "clicked": 7, "reply_rate": 22, "open_rate": null, "click_rate": 17 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/enrollment-statuses": { "get": { "operationId": "listCampaignEnrollmentStatuses", "summary": "List enrollment status groups", "description": "The status groups you can filter enrollees by in `POST /v1/campaigns/{id}/enrollments/search`. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Enrollment status groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignEnrollmentStatusesResponse" }, "example": { "success": true, "data": [ { "value": "running", "label": "Running", "description": "Still in the campaign, waiting for their next step." }, { "value": "awaiting_task", "label": "Awaiting task", "description": "Held until a task step is marked done." }, { "value": "replied", "label": "Replied", "description": "Replied, so the campaign stopped for them." }, { "value": "meeting_booked", "label": "Meeting booked", "description": "Booked a meeting." }, { "value": "bounced", "label": "Bounced", "description": "An email to them bounced." }, { "value": "completed", "label": "Completed", "description": "Went through every step." }, { "value": "stopped", "label": "Stopped", "description": "Stopped, cancelled or failed before finishing." } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches": { "post": { "operationId": "createCampaignEnrollmentBatch", "summary": "Prepare an enrollment", "description": "Creates a draft enrollment batch: checks every person, fills their variables and writes each person's final emails. Nothing is enrolled or sent until you call start. Each person comes back `ready`, `needs_input` or `blocked` with the reasons in `issues`; fix people with `PATCH .../recipients/{recipient_id}`. When the campaign uses AI variables the batch is `preparing` while they are written; read it again until it is `ready`. A draft expires 24 hours after its last change. With API keys, MCP and Ask Dex together, a workspace can enroll up to 500 people in 24 hours by default (`429 DAILY_ENROLLMENT_LIMIT_REACHED`). Needs `campaigns:enroll`.\n\nSigned-in users need access to campaigns in their role. API keys need the campaigns permission named on each endpoint.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchCreateRequest" }, "example": { "sender_team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "from_email": "riya@acmetalent.com", "job_id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "job_pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88", "start_mode": "scheduled", "start_at": "2026-10-19T09:00:00", "start_timezone": "Europe/London", "variable_values": { "custom": "We placed 3 engineers at Monzo last year." }, "recipients": [ { "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "variable_values": { "personalization_line": "Loved your PyCon talk on async Python." }, "blank_variables": [ "custom" ] }, { "person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73" }, { "person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24" }, { "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "variable_values": { "personalization_line": "Your QCon London talk was great." } } ] } } } }, "responses": { "201": { "description": "Batch prepared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchResponse" }, "example": { "success": true, "data": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "status": "preparing", "version": 1, "source": "api", "campaign": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo" }, "sender": { "team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "name": "Riya Kapoor", "from_email": "riya@acmetalent.com" }, "job": { "id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "title": "Senior Backend Engineer", "pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88", "pipeline_stage": "Contacted" }, "start": { "mode": "scheduled", "at": "2026-10-19T08:00:00.000Z", "timezone": "Europe/London" }, "created_by": { "type": "api_key", "id": "0d4b8f2e-6a1c-4e9b-b3d7-5f2a8c1e4b96", "name": "Greenhouse sync" }, "created_at": "2026-10-13T11:20:00.000Z", "expires_at": "2026-10-14T11:20:00.000Z", "started_at": null, "progress": { "done": 1, "total": 4 }, "summary": { "total": 4, "preparing": 3, "ready": 0, "needs_input": 0, "blocked": 1, "excluded": 0, "enrolled": 0, "rejected_at_start": 0 }, "warnings": [], "recipients": [ { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "preparing", "issues": [ { "code": "enrolled_in_other_campaign", "message": "Also in 'Q4 platform engineers' (running).", "details": { "campaigns": [ "Q4 platform engineers" ] } } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32", "person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73", "name": "Tom Reed", "email": "tom@reed.dev", "status": "preparing", "issues": [], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "c3e5a7b9-4d6f-4b8c-ae2a-3f5b7d9c1e43", "person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24", "name": "Priya Shah", "email": "priya@shah.io", "status": "blocked", "issues": [ { "code": "unsubscribed", "message": "Unsubscribed from your emails on 2 Sep 2026." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "d4f6b8ca-5e7a-4c9d-bf3b-4a6c8e0d2f54", "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "name": "Mark Chen", "email": "mark.chen@gmail.com", "status": "preparing", "issues": [ { "code": "company_do_not_contact", "message": "Works at Globex, which is marked do not contact. Override with a reason to include them.", "details": { "companies": [ "Globex" ] } }, { "code": "likely_bounce", "message": "This email looks risky and may bounce." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null } ], "sample": null } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The campaign is archived or has no steps, or the mailbox is disconnected (CAMPAIGN_ARCHIVED, CAMPAIGN_HAS_NO_STEPS, MAILBOX_DISCONNECTED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Daily enrollment limit reached (DAILY_ENROLLMENT_LIMIT_REACHED), or rate limited (RATE_LIMIT_EXCEEDED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches/{batch_id}": { "get": { "operationId": "getCampaignEnrollmentBatch", "summary": "Get an enrollment batch", "description": "The batch's people with their status and issues, warnings, one sample email, and the `version` and `summary.ready` to pass to start. Add `include=content` for every person's final steps. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" }, { "schema": { "type": "string", "enum": [ "content" ], "description": "content: also return every person's final steps." }, "required": false, "description": "content: also return every person's final steps.", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchResponse" }, "example": { "success": true, "data": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "status": "ready", "version": 2, "source": "api", "campaign": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo" }, "sender": { "team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "name": "Riya Kapoor", "from_email": "riya@acmetalent.com" }, "job": { "id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "title": "Senior Backend Engineer", "pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88", "pipeline_stage": "Contacted" }, "start": { "mode": "scheduled", "at": "2026-10-19T08:00:00.000Z", "timezone": "Europe/London" }, "created_by": { "type": "api_key", "id": "0d4b8f2e-6a1c-4e9b-b3d7-5f2a8c1e4b96", "name": "Greenhouse sync" }, "created_at": "2026-10-13T11:20:00.000Z", "expires_at": "2026-10-14T11:20:40.000Z", "started_at": null, "progress": null, "summary": { "total": 4, "preparing": 0, "ready": 1, "needs_input": 2, "blocked": 1, "excluded": 0, "enrolled": 0, "rejected_at_start": 0 }, "warnings": [ { "code": "adds_to_job_pipeline", "message": "1 person will be added to Senior Backend Engineer at Contacted.", "details": { "count": 1 } }, { "code": "job_automation_will_run", "message": "Moving people to this stage starts these automations: Notify hiring manager.", "details": { "automations": [ "Notify hiring manager" ] } } ], "recipients": [ { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "ready", "issues": [ { "code": "enrolled_in_other_campaign", "message": "Also in 'Q4 platform engineers' (running).", "details": { "campaigns": [ "Q4 platform engineers" ] } } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": "2026-10-19T08:00:00.000Z", "steps": [ { "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam,

Your work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.

You can see the role here. Open to a chat?

Riya
", "edited": false }, { "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam, following up on my note.

Riya
", "edited": false }, { "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call Sam if they opened but did not reply.
", "edited": false } ] }, { "recipient_id": "b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32", "person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73", "name": "Tom Reed", "email": "tom@reed.dev", "status": "needs_input", "issues": [ { "code": "missing_variables", "message": "Fill in or leave blank: personalization_line.", "details": { "variables": [ "personalization_line" ] } } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null, "steps": [ { "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Tom,

Your Kafka migration at Deliveroo stood out. I'm hiring a Senior Backend Engineer at Monzo. {{personalization_line}}

You can see the role here. Open to a chat?

Riya
", "edited": false }, { "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Tom, following up on my note. We placed 3 engineers at Monzo last year.

Riya
", "edited": false }, { "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call Tom if they opened but did not reply.
", "edited": false } ] }, { "recipient_id": "c3e5a7b9-4d6f-4b8c-ae2a-3f5b7d9c1e43", "person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24", "name": "Priya Shah", "email": "priya@shah.io", "status": "blocked", "issues": [ { "code": "unsubscribed", "message": "Unsubscribed from your emails on 2 Sep 2026." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null, "steps": [] }, { "recipient_id": "d4f6b8ca-5e7a-4c9d-bf3b-4a6c8e0d2f54", "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "name": "Mark Chen", "email": "mark.chen@gmail.com", "status": "needs_input", "issues": [ { "code": "company_do_not_contact", "message": "Works at Globex, which is marked do not contact. Override with a reason to include them.", "details": { "companies": [ "Globex" ] } }, { "code": "likely_bounce", "message": "This email looks risky and may bounce." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null, "steps": [ { "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Mark,

Leading the ledger rebuild at Globex stood out. I'm hiring a Senior Backend Engineer at Monzo. Your QCon London talk was great.

You can see the role here. Open to a chat?

Riya
", "edited": false }, { "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Mark, following up on my note. We placed 3 engineers at Monzo last year.

Riya
", "edited": false }, { "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call Mark if they opened but did not reply.
", "edited": false } ] } ], "sample": { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "subject": "Senior Backend Engineer role at Monzo", "body_text": "Hi Sam,\n\nYour work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.\n\nYou can see the role here (https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2). Open to a chat?\n\nRiya" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients/{recipient_id}": { "get": { "operationId": "getCampaignEnrollmentBatchRecipient", "summary": "Get one person in a batch", "description": "One person's variables, where each value came from, and their final steps. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The person's recipient_id in the batch (not their person_id)." }, "required": true, "description": "The person's recipient_id in the batch (not their person_id).", "name": "recipient_id", "in": "path" } ], "responses": { "200": { "description": "Person", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchRecipientResponse" }, "example": { "success": true, "data": { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "ready", "issues": [ { "code": "enrolled_in_other_campaign", "message": "Also in 'Q4 platform engineers' (running).", "details": { "campaigns": [ "Q4 platform engineers" ] } } ], "enrollment_id": null, "first_email_estimated_at": "2026-10-19T08:00:00.000Z", "add_email_to_person": false, "overrides": [], "override_reason": null, "blank_variables": [ "custom" ], "variables": { "first_name": { "value": "Sam", "source": "person" }, "search_name": { "value": "Senior Backend Engineer", "source": "job" }, "search_client": { "value": "Monzo", "source": "job" }, "application_link": { "value": "https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2", "source": "job" }, "sender_first_name": { "value": "Riya", "source": "sender" }, "personalization_line": { "value": "Loved your PyCon talk on async Python.", "source": "provided" }, "ai:opening_line": { "value": "Your work scaling payments at Wise stood out.", "source": "ai" } }, "steps": [ { "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam,

Your work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.

You can see the role here. Open to a chat?

Riya
", "edited": false }, { "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam, following up on my note.

Riya
", "edited": false }, { "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call Sam if they opened but did not reply.
", "edited": false } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateCampaignEnrollmentBatchRecipient", "summary": "Change one person in a batch", "description": "Change the email, fill in or leave out variables, override a do-not-contact or duplicate block with a reason, set the final text of their steps, or exclude them. The person is checked again and comes back with their new status. Raises the batch `version`. Changes to different people can be sent at the same time; send all changes to one person in one request, since two at once return `409 BATCH_VERSION_CHANGED`. Only the API key or person who created the batch can change it. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The person's recipient_id in the batch (not their person_id)." }, "required": true, "description": "The person's recipient_id in the batch (not their person_id).", "name": "recipient_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchRecipientUpdateRequest" }, "example": { "blank_variables": [ "custom" ] } } } }, "responses": { "200": { "description": "Person updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchRecipientResponse" }, "example": { "success": true, "data": { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "ready", "issues": [ { "code": "enrolled_in_other_campaign", "message": "Also in 'Q4 platform engineers' (running).", "details": { "campaigns": [ "Q4 platform engineers" ] } } ], "enrollment_id": null, "first_email_estimated_at": "2026-10-19T08:00:00.000Z", "add_email_to_person": false, "overrides": [], "override_reason": null, "blank_variables": [ "custom" ], "variables": { "first_name": { "value": "Sam", "source": "person" }, "search_name": { "value": "Senior Backend Engineer", "source": "job" }, "search_client": { "value": "Monzo", "source": "job" }, "application_link": { "value": "https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2", "source": "job" }, "sender_first_name": { "value": "Riya", "source": "sender" }, "personalization_line": { "value": "Loved your PyCon talk on async Python.", "source": "provided" }, "ai:opening_line": { "value": "Your work scaling payments at Wise stood out.", "source": "ai" } }, "steps": [ { "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "send_after_days": 0, "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam,

Your work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.

You can see the role here. Open to a chat?

Riya
", "edited": false }, { "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "send_after_days": 3, "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam, following up on my note.

Riya
", "edited": false }, { "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "send_after_days": 2, "subject": null, "body_html": "
Call Sam if they opened but did not reply.
", "edited": false } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The batch is preparing, has started or was discarded, or another change to it landed first (BATCH_PREPARING, BATCH_NOT_EDITABLE, BATCH_VERSION_CHANGED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "410": { "description": "The draft expired 24 hours after its last change (BATCH_EXPIRED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients": { "post": { "operationId": "addCampaignEnrollmentBatchRecipients", "summary": "Add people to a batch", "description": "Adds people to a ready batch, checked the same way as at create. When the campaign uses AI variables and you don't pass them, the batch is `preparing` again while they are written. Raises `version`. If another change to the batch lands first, it returns `409 BATCH_VERSION_CHANGED`: read the batch and add them again. Only the API key or person who created the batch can change it. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchAddRecipientsRequest" }, "example": { "recipients": [ { "person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76", "variable_values": { "personalization_line": "Your Monzo meetup talk was great.", "ai:opening_line": "Your work on the card payments platform stood out." } } ] } } } }, "responses": { "200": { "description": "People added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchResponse" }, "example": { "success": true, "data": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "status": "ready", "version": 3, "source": "api", "campaign": { "id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84", "name": "Senior Backend Engineer, Monzo" }, "sender": { "team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "name": "Riya Kapoor", "from_email": "riya@acmetalent.com" }, "job": { "id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "title": "Senior Backend Engineer", "pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88", "pipeline_stage": "Contacted" }, "start": { "mode": "scheduled", "at": "2026-10-19T08:00:00.000Z", "timezone": "Europe/London" }, "created_by": { "type": "api_key", "id": "0d4b8f2e-6a1c-4e9b-b3d7-5f2a8c1e4b96", "name": "Greenhouse sync" }, "created_at": "2026-10-13T11:20:00.000Z", "expires_at": "2026-10-14T11:24:10.000Z", "started_at": null, "progress": null, "summary": { "total": 5, "preparing": 0, "ready": 2, "needs_input": 2, "blocked": 1, "excluded": 0, "enrolled": 0, "rejected_at_start": 0 }, "warnings": [ { "code": "adds_to_job_pipeline", "message": "2 people will be added to Senior Backend Engineer at Contacted.", "details": { "count": 2 } }, { "code": "contains_overrides", "message": "Ana Ruiz is enrolled despite a do-not-contact or duplicate block.", "details": { "count": 1, "names": [ "Ana Ruiz" ] } }, { "code": "job_automation_will_run", "message": "Moving people to this stage starts these automations: Notify hiring manager.", "details": { "automations": [ "Notify hiring manager" ] } } ], "recipients": [ { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "ready", "issues": [ { "code": "enrolled_in_other_campaign", "message": "Also in 'Q4 platform engineers' (running).", "details": { "campaigns": [ "Q4 platform engineers" ] } } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": "2026-10-19T08:00:00.000Z" }, { "recipient_id": "b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32", "person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73", "name": "Tom Reed", "email": "tom@reed.dev", "status": "needs_input", "issues": [ { "code": "missing_variables", "message": "Fill in or leave blank: personalization_line.", "details": { "variables": [ "personalization_line" ] } } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "c3e5a7b9-4d6f-4b8c-ae2a-3f5b7d9c1e43", "person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24", "name": "Priya Shah", "email": "priya@shah.io", "status": "blocked", "issues": [ { "code": "unsubscribed", "message": "Unsubscribed from your emails on 2 Sep 2026." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "d4f6b8ca-5e7a-4c9d-bf3b-4a6c8e0d2f54", "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "name": "Mark Chen", "email": "mark.chen@gmail.com", "status": "needs_input", "issues": [ { "code": "company_do_not_contact", "message": "Works at Globex, which is marked do not contact. Override with a reason to include them.", "details": { "companies": [ "Globex" ] } }, { "code": "likely_bounce", "message": "This email looks risky and may bounce." } ], "overrides": [], "override_reason": null, "enrollment_id": null, "first_email_estimated_at": null }, { "recipient_id": "e5a7c9db-6f8b-4dae-8c4d-5b7d9f1e3a65", "person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76", "name": "Ana Ruiz", "email": "ana.ruiz@gmail.com", "status": "ready", "issues": [ { "code": "previously_in_campaign", "message": "Was in this campaign before at ana.ruiz@gmail.com: enrolled 2 Sep 2026, then stopped.", "details": { "enrollment_id": "1c3e5a7b-8d9f-4a2c-b4e6-7f9a1c3e5b87", "status": "stopped", "enrolled_at": "2026-09-02T09:30:00.000Z" } } ], "overrides": [ "company_do_not_contact" ], "override_reason": "Their hiring manager asked us to reach out.", "enrollment_id": null, "first_email_estimated_at": "2026-10-19T08:00:00.000Z" } ], "sample": { "recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21", "subject": "Senior Backend Engineer role at Monzo", "body_text": "Hi Sam,\n\nYour work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.\n\nYou can see the role here (https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2). Open to a chat?\n\nRiya" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The batch is preparing, has started or was discarded, or another change to it landed first (BATCH_PREPARING, BATCH_NOT_EDITABLE, BATCH_VERSION_CHANGED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "410": { "description": "The draft expired 24 hours after its last change (BATCH_EXPIRED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches/{batch_id}/start": { "post": { "operationId": "startCampaignEnrollmentBatch", "summary": "Start an enrollment", "description": "Enrolls every `ready` person with exactly the emails stored on the batch. Pass the `version` and `summary.ready` you read, so nothing you haven't seen is sent; if either changed you get `409` and nothing is enrolled. Everyone is checked again: a person who unsubscribed or was enrolled in this campaign by someone else in the meantime is listed in `rejected_at_start` and the rest are enrolled. Calling start again is safe: it returns or finishes the first result with `replayed: true`. To undo a start, stop the batch with `POST /v1/campaigns/{id}/enrollments/stop`. Only the API key or person who created the batch can start it. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchStartRequest" }, "example": { "version": 5, "expected_recipient_count": 4, "from_email": "riya@acmetalent.com" } } } }, "responses": { "200": { "description": "Enrolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchStartResponse" }, "example": { "success": true, "data": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "status": "starting", "replayed": false, "summary": { "enrolled": 3, "rejected_at_start": 1, "not_enrolled": 1 }, "enrollments": [ { "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "enrollment_id": "e7b1d3f5-9a2c-4e6b-8d0f-3a5c7e9b1d42", "first_email_estimated_at": "2026-10-19T08:00:00.000Z" }, { "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "enrollment_id": "f3a5c7e9-1b3d-4f6a-8c2e-4d6f8a0c2e57", "first_email_estimated_at": "2026-10-19T08:00:00.000Z" }, { "person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76", "enrollment_id": "a9c1e3f5-7b2d-4e8a-9c4f-6e8a0c2e4b18", "first_email_estimated_at": "2026-10-19T08:00:00.000Z" } ], "not_enrolled": [ { "person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24", "status": "blocked" } ], "rejected_at_start": [ { "person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73", "issues": [ { "code": "person_do_not_contact", "message": "Marked do not contact." } ] } ], "follow_up_errors": [ { "person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95", "message": "Enrolled, but adding them to the job didn't finish. It is retried automatically." } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The batch changed since you read it (BATCH_VERSION_CHANGED, RECIPIENT_COUNT_MISMATCH), is preparing or can no longer start (BATCH_PREPARING, BATCH_NOT_EDITABLE), the campaign changed or was archived (BATCH_STALE, CAMPAIGN_ARCHIVED), the scheduled start passed (START_TIME_PASSED), nobody is ready (NOTHING_TO_ENROLL), or the mailbox differs or is disconnected (SENDER_MISMATCH, MAILBOX_DISCONNECTED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "410": { "description": "The draft expired 24 hours after its last change (BATCH_EXPIRED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Daily enrollment limit reached (DAILY_ENROLLMENT_LIMIT_REACHED), or rate limited (RATE_LIMIT_EXCEEDED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollment-batches/{batch_id}/discard": { "post": { "operationId": "discardCampaignEnrollmentBatch", "summary": "Discard an enrollment batch", "description": "Throws away a draft that has not started; nobody is enrolled. Only the API key or person who created the batch can discard it. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment batch ID." }, "required": true, "description": "Enrollment batch ID.", "name": "batch_id", "in": "path" } ], "responses": { "200": { "description": "Discarded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBatchDiscardResponse" }, "example": { "success": true, "data": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "status": "discarded" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The batch has started or was discarded (BATCH_NOT_EDITABLE)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "410": { "description": "The draft expired 24 hours after its last change (BATCH_EXPIRED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollments/search": { "post": { "operationId": "searchCampaignEnrollments", "summary": "Search enrollees", "description": "People enrolled in the campaign with their status, current step, next step time, opens, clicks and reply intent. Filter by status group, person, job, enrollment batch, source, enrollment date, current step, reply intent, opens, clicks, or name and email; sort by enrollment date, name, status, next step time, opens or clicks. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentsSearchBody" }, "example": { "status": "running", "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "sort_by": "next_step_at", "sort_order": "asc" } } } }, "responses": { "200": { "description": "Enrollees found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentsSearchResponse" }, "example": { "success": true, "data": [ { "id": "e7b1d3f5-9a2c-4e6b-8d0f-3a5c7e9b1d42", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "active", "status_group": "running", "from_email": "riya@acmetalent.com", "sender_team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "job_id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "enrolled_at": "2026-10-13T11:31:05.000Z", "current_step": 2, "next_step_at": "2026-10-22T09:14:00.000Z", "opens": 0, "clicks": 1, "reply_intent": null, "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "source": "api" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollments/{enrollment_id}": { "get": { "operationId": "getCampaignEnrollment", "summary": "Get an enrollee", "description": "One enrollee with every step: what was sent, what is still to come, and which steps can still be edited. Needs `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment ID." }, "required": true, "description": "Enrollment ID.", "name": "enrollment_id", "in": "path" } ], "responses": { "200": { "description": "Enrollee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignEnrollmentResponse" }, "example": { "success": true, "data": { "id": "e7b1d3f5-9a2c-4e6b-8d0f-3a5c7e9b1d42", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "active", "status_group": "running", "from_email": "riya@acmetalent.com", "sender_team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "job_id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "enrolled_at": "2026-10-13T11:31:05.000Z", "current_step": 2, "next_step_at": "2026-10-22T09:14:00.000Z", "opens": 0, "clicks": 1, "reply_intent": null, "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "source": "api", "steps": [ { "id": "f8a2c4e6-0b3d-4f5a-9c7e-1b3d5f7a9c08", "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam,

Your work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.

You can see the role here. Open to a chat?

Riya
", "status": "sent", "due_at": "2026-10-19T08:00:00.000Z", "sent_at": "2026-10-19T08:03:41.000Z", "editable": false }, { "id": "0c4e6a8b-2d5f-4a7c-8e9b-3d5f7b9a1c19", "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam, following up on my note.

Riya
", "status": "pending", "due_at": "2026-10-22T09:14:00.000Z", "sent_at": null, "editable": true }, { "id": "6e8a0c2d-4f7b-4c9e-8a1d-5f7b9d1e3a20", "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "subject": null, "body_html": "
Call Sam if they opened but did not reply.
", "status": "pending", "due_at": null, "sent_at": null, "editable": true } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollments/{enrollment_id}/steps/{step_id}": { "patch": { "operationId": "updateCampaignEnrollmentStep", "summary": "Edit an enrollee's upcoming step", "description": "Change the subject or body of one step that has not been sent and is not being sent right now, for this person only. Use the final text, with no `{{variables}}`. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Enrollment ID." }, "required": true, "description": "Enrollment ID.", "name": "enrollment_id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Step ID from the enrollment's steps (not the campaign step)." }, "required": true, "description": "Step ID from the enrollment's steps (not the campaign step).", "name": "step_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentStepUpdateRequest" }, "example": { "body_html": "
Hi Sam, following up on my note about the Monzo role.

Riya
" } } } }, "responses": { "200": { "description": "Step updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignEnrollmentResponse" }, "example": { "success": true, "data": { "id": "e7b1d3f5-9a2c-4e6b-8d0f-3a5c7e9b1d42", "person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40", "name": "Sam Patel", "email": "sam@gmail.com", "status": "active", "status_group": "running", "from_email": "riya@acmetalent.com", "sender_team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20", "job_id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13", "enrolled_at": "2026-10-13T11:31:05.000Z", "current_step": 2, "next_step_at": "2026-10-22T09:14:00.000Z", "opens": 0, "clicks": 1, "reply_intent": null, "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34", "source": "api", "steps": [ { "id": "f8a2c4e6-0b3d-4f5a-9c7e-1b3d5f7a9c08", "step_id": "5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43", "order": 1, "type": "email", "subject": "Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam,

Your work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.

You can see the role here. Open to a chat?

Riya
", "status": "sent", "due_at": "2026-10-19T08:00:00.000Z", "sent_at": "2026-10-19T08:03:41.000Z", "editable": false }, { "id": "0c4e6a8b-2d5f-4a7c-8e9b-3d5f7b9a1c19", "step_id": "9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17", "order": 2, "type": "email", "subject": "Re: Senior Backend Engineer role at Monzo", "body_html": "
Hi Sam, following up on my note about the Monzo role.

Riya
", "status": "pending", "due_at": "2026-10-22T09:14:00.000Z", "sent_at": null, "editable": true }, { "id": "6e8a0c2d-4f7b-4c9e-8a1d-5f7b9d1e3a20", "step_id": "c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90", "order": 3, "type": "manual", "subject": null, "body_html": "
Call Sam if they opened but did not reply.
", "status": "pending", "due_at": null, "sent_at": null, "editable": true } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The step was sent or is sending (STEP_NOT_EDITABLE)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/campaigns/{id}/enrollments/stop": { "post": { "operationId": "stopCampaignEnrollments", "summary": "Stop enrollees", "description": "Stops up to 500 enrollees of this campaign by enrollment id, or everyone one enrollment batch enrolled (`batch_id`), which undoes its start. Pass one of the two. People who already replied, booked a meeting, finished or were stopped are left as they are and not counted. Needs `campaigns:enroll`.", "tags": [ "Campaigns" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "required": true, "description": "Campaign ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentsStopRequest" }, "examples": { "By enrollment ids": { "summary": "Stop people by enrollment id", "value": { "enrollment_ids": [ "e7b1d3f5-9a2c-4e6b-8d0f-3a5c7e9b1d42", "f3a5c7e9-1b3d-4f6a-8c2e-4d6f8a0c2e57" ] } }, "By batch": { "summary": "Stop everyone one batch enrolled", "value": { "batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34" } } } } } }, "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentStopResponse" }, "example": { "success": true, "data": { "stopped_enrollment_count": 2 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "No access to campaigns, or the API key lacks the permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The batch has not started (BATCH_NOT_STARTED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/candidates/update-stage": { "post": { "operationId": "updateCandidateStage", "summary": "Update candidate stage", "description": "Moves a candidate to a different pipeline stage within a job.\n\n**Flexible identification**: Accepts job identification by `job_id` or `job_name`, candidate identification by `candidate_id`, `candidate_email`, or `candidate_name`, and stage identification by `stage_id` or `stage_name`.\n\n**Job resolution**: The endpoint resolves the job in this order: `job_id`, the job associated with `candidate_id`, `job_name`, then the person's most recent active candidacy created within the previous 180 days. When `candidate_id` is provided, its associated job takes precedence over `job_name`.\n\n**Discovering stage IDs/names**: Use `GET /v1/jobs/{id}` to see the full `pipeline_stages` array with stage IDs, names, and ordering for a specific job.\n\n**Archived stages**: A stage archived on the job keeps the candidates already in it, but no one can be moved into it. Targeting one returns `400` with code `STAGE_ARCHIVED`. Requesting the archived stage a candidate is already in returns their current state unchanged.\n\n**Rejection details**: When moving to a stage where `is_rejection_stage` is true, optionally pass `rejection_reason_id` from `GET /v1/candidates/rejection-reasons` and `reason_text` for additional context. Rejection details are not allowed for non-rejection stages. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident.", "tags": [ "Candidates" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCandidateStageBody" } } } }, "responses": { "200": { "description": "Stage updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCandidateStageResponse" }, "example": { "success": true, "data": { "candidate_id": "123e4567-e89b-12d3-a456-426614174000", "person_id": "234e5678-e90a-12b3-c456-789012345678", "job_id": "234e5678-e90a-12b3-c456-789012345678", "previous_stage_id": "345e6789-e01b-23c4-d567-890123456789", "new_stage_id": "456e7890-e12b-34d5-a678-901234567890", "pipeline_status_id": "567e8901-e23c-45d6-e789-012345678901", "reason_text": "The role requires deeper enterprise sales experience.", "rejection_reason": { "id": "789e0123-a45b-67c8-d901-234567890123", "reason": "Insufficient relevant experience" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/candidates/rejection-reasons": { "get": { "operationId": "listRejectionReasons", "summary": "List rejection reasons", "description": "Retrieve active rejection reasons configured for the requesting team. Use a returned `id` as `rejection_reason_id` when moving a candidate to a rejection stage with `POST /v1/candidates/update-stage`.", "tags": [ "Candidates" ], "responses": { "200": { "description": "Rejection reasons fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectionReasonsListResponse" }, "example": { "success": true, "data": [ { "id": "789e0123-a45b-67c8-d901-234567890123", "reason": "Insufficient relevant experience" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/candidates/{id}": { "get": { "operationId": "getCandidateById", "summary": "Get candidate by ID", "description": "Retrieve detailed information about a single candidate including their full pipeline stage history (all stages they have been through with dates).\n\n**When to use**: Use this when you need the stage history timeline for one specific candidate. For querying multiple candidates with filtering, use `POST /v1/persons/search` with `job_id` and `include: [\"candidates\"]` instead.", "tags": [ "Candidates" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Candidate ID" } } ], "responses": { "200": { "description": "Candidate fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateByIdResponse" }, "example": { "success": true, "data": { "id": "234e5678-e90a-12b3-c456-789012345678", "person_id": "345e6789-e01b-23c4-d567-890123456789", "job_id": "123e4567-e89b-12d3-a456-426614174000", "name": "Jane Smith", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "current_pipeline_stage_date": "2024-01-15T10:00:00Z", "created_at": "2024-01-12T14:30:00Z", "sourced_by": "678e9012-e34d-56f7-a890-123456789012", "owner_id": "678e9012-e34d-56f7-a890-123456789012", "pipeline_stage_history": [ { "stage_id": "345e6789-e01b-23c4-d567-890123456789", "stage_name": "Application Review", "stage_date": "2024-01-12T14:30:00Z", "pipeline_status_id": "456e7890-e12b-34d5-a678-901234567890", "reason_text": null, "rejection_reason": null }, { "stage_id": "567e8901-e23c-45d6-e789-012345678901", "stage_name": "Technical Interview", "stage_date": "2024-01-15T10:00:00Z", "pipeline_status_id": "678e9012-f34a-56b7-c890-123456789012", "reason_text": null, "rejection_reason": null } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteCandidate", "summary": "Remove candidate from job", "description": "Remove a candidate from a job pipeline (soft archive).\n\n**Important**: This only removes the candidacy — the association between the person and the job. The **person record remains in the database** and is not deleted. Stage history and other job-linked candidacy data stay retained on the archived candidate row.\n\nTo add the person back to a job later, use `POST /v1/persons` or `PATCH /v1/persons/{id}` with `job_id` (or the matching MCP tools). Get candidate IDs from `POST /v1/persons/search` with `include: [\"candidates\"]` or from `GET /v1/candidates/{id}`.\n\nRequires the `candidates:delete` API key scope.", "tags": [ "Candidates" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Candidate UUID" } } ], "responses": { "200": { "description": "Candidate removed from job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Candidate removed from job successfully. The person record was not deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/client-contacts/statuses": { "get": { "operationId": "listClientContactStatuses", "summary": "List client contact statuses", "description": "Returns all client contact statuses for the organization, ordered by stage_order. No pagination — the full list is always returned.\n\n**When to use**: Call this to discover available status IDs for `client_contact_status_id` when listing, fetching, creating, or updating client contacts.", "tags": [ "Client Contacts" ], "responses": { "200": { "description": "Client contact statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientContactStatusesListResponse" }, "example": { "success": true, "data": [ { "id": "890e1234-f56a-78b9-c012-345678901234", "name": "Active", "color": "#3b82f6", "stage_order": 1, "is_default_status": true }, { "id": "901f2345-a67b-89c0-d123-456789012345", "name": "Churned", "color": "#ef4444", "stage_order": 2, "is_default_status": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/client-contacts": { "get": { "operationId": "listClientContacts", "summary": "List client contacts", "description": "Retrieve a paginated list of client contacts, including the linked person, client company, and status in each row.\n\n**Filters**: `person_id`, `client_id` (company UUID), `client_contact_status_id`, `is_referral_partner`, and `keywords` (contact name contains the text, case-insensitive).\n\n**Sorting**: `sort_by` (`created_at` or `updated_at`) with `sort_order` (`asc` or `desc`, default `desc`). With `keywords`, results are sorted by name A to Z instead.\n\n**Referral partners**: each contact has `is_referral_partner` and `referred_jobs`, the jobs it referred that you can see.\n\n**Pagination**: Use `offset` and `limit` query params (max 100 per page).\n\n**Access**: Session and OAuth callers who cannot view CRM data but can edit jobs (`org:jobs:edit`) may search by `keywords` only, without a `client_contact_status_id` filter. Their results keep the person name and company; status, owners, job title and image are returned empty.\n\nDeleted client contacts are omitted.", "tags": [ "Client Contacts" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Return only the client contact linked to this person UUID." }, "required": false, "name": "person_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Return only client contacts linked to this client company UUID." }, "required": false, "name": "client_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Return only client contacts with this status UUID. Use GET /v1/client-contacts/statuses to discover status IDs." }, "required": false, "name": "client_contact_status_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 200, "description": "Return only contacts whose name contains this text (case-insensitive, matched literally). Results are then sorted by name A to Z, and sort_by and sort_order are ignored." }, "required": false, "description": "Return only contacts whose name contains this text (case-insensitive, matched literally). Results are then sorted by name A to Z, and sort_by and sort_order are ignored.", "name": "keywords", "in": "query" }, { "schema": { "type": "boolean", "description": "true returns only contacts who are a referral partner on at least one job; false returns only contacts who are not. Omit for both." }, "required": false, "description": "true returns only contacts who are a referral partner on at least one job; false returns only contacts who are not. Omit for both.", "name": "is_referral_partner", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at", "description": "Column to sort results by. Defaults to `created_at`.\n- `created_at` — when the client contact was created\n- `updated_at` — when the client contact was last updated" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (newest first)." }, "required": false, "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "Client contacts fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientContactsListResponse" }, "example": { "success": true, "data": [ { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "person_id": "fff66666-0000-1111-2222-333333336666", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234", "person": { "id": "fff66666-0000-1111-2222-333333336666", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee", "current_job_title": "Head of Talent", "image_url": "https://example.com/jordan-lee.png", "date_of_last_engagement": "2024-01-28T16:45:00Z" }, "company": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "name": "Acme Corp", "domain": "acme.example.com" }, "status": { "id": "890e1234-f56a-78b9-c012-345678901234", "name": "Active", "color": "#3b82f6", "stage_order": 1, "is_default_status": true }, "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444" ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-02-01T09:30:00Z", "is_referral_partner": true, "referred_jobs": [ { "job_id": "123e4567-e89b-12d3-a456-426614174000", "job_title": "Senior Software Engineer" } ] } ], "meta": { "total": 42, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "createClientContact", "summary": "Create client contact", "description": "Promote an existing person into a client contact by linking them to a client company. The associated company is automatically flagged as a client.\n\n**Idempotency**: A person can be an active client contact for at most one client company per team (DB constraint). If a non-deleted client contact already exists for this person, the existing record is returned with `is_new: false` and the echoed `client_id` reflects the contact's actual client company — compare it to the requested `client_id` to detect mismatches. New contacts return 201 with `is_new: true`; existing contacts return 200.\n\n**Status**: When `client_contact_status_id` is omitted, the team default status is assigned. Pass null to leave the new contact without a status.\n\n**Owners**: When `owner_ids` is omitted, the authenticated caller is auto-assigned (if they are a team member). Pass an empty array to create a contact with no owners.", "tags": [ "Client Contacts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientContactRequest" } } } }, "responses": { "200": { "description": "Existing client contact returned (no duplicate created)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientContactResponse" }, "example": { "success": true, "data": { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "person_id": "fff66666-0000-1111-2222-333333336666", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234", "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444" ], "created_at": "2024-01-15T10:00:00Z", "is_new": false } } } } }, "201": { "description": "Client contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientContactResponse" }, "example": { "success": true, "data": { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "person_id": "fff66666-0000-1111-2222-333333336666", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234", "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444" ], "created_at": "2024-01-15T10:00:00Z", "is_new": true } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/client-contacts/{id}": { "get": { "operationId": "getClientContactById", "summary": "Get client contact by ID", "description": "Retrieve a single client contact, including the linked person, client company, status, and the jobs it referred.\n\n**ID**: Accepts a client contact UUID or a person UUID — if a person UUID is provided, the associated client contact is resolved automatically.", "tags": [ "Client Contacts" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Client contact UUID or person UUID." } } ], "responses": { "200": { "description": "Client contact fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientContactByIdResponse" }, "example": { "success": true, "data": { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "person_id": "fff66666-0000-1111-2222-333333336666", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234", "person": { "id": "fff66666-0000-1111-2222-333333336666", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee", "current_job_title": "Head of Talent", "image_url": "https://example.com/jordan-lee.png", "date_of_last_engagement": "2024-01-28T16:45:00Z" }, "company": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "name": "Acme Corp", "domain": "acme.example.com" }, "status": { "id": "890e1234-f56a-78b9-c012-345678901234", "name": "Active", "color": "#3b82f6", "stage_order": 1, "is_default_status": true }, "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444" ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-02-01T09:30:00Z", "is_referral_partner": true, "referred_jobs": [ { "job_id": "123e4567-e89b-12d3-a456-426614174000", "job_title": "Senior Software Engineer" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateClientContact", "summary": "Update client contact", "description": "Update a client contact's status, owners, or both. Omitted fields remain unchanged; at least one of `client_contact_status_id` or `owner_ids` is required.\n\n**ID**: Accepts a client contact UUID or a person UUID — if a person UUID is provided, the associated client contact is resolved automatically.\n\n**Status**: Pass a valid status UUID to change the status, or null to clear it. Use GET /v1/client-contacts/statuses to discover available status IDs.\n\n**Owners**: Pass `owner_ids` to set the client contact owners. The list replaces all current owners; pass an empty array to remove every owner. Get team member IDs from GET /v1/team-members.", "tags": [ "Client Contacts" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Client contact UUID or person UUID." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientContactRequest" } } } }, "responses": { "200": { "description": "Client contact updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientContactResponse" }, "example": { "success": true, "data": { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234", "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444", "eee55555-ffff-0000-1111-222222225555" ], "message": "Client contact updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies/statuses": { "get": { "operationId": "listCompanyClientStatuses", "summary": "List company client statuses", "description": "Returns all company client statuses for the organization, ordered by stage_order. No pagination — the full list is always returned.\n\n**When to use**: Call this to discover available status IDs for `company_status_ids_included` / `company_status_ids_excluded` filters in `POST /v1/companies/search`, or for `client_status_id` when updating companies.", "tags": [ "Companies" ], "responses": { "200": { "description": "Company client statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyClientStatusesListResponse" }, "example": { "success": true, "data": [ { "id": "789e0123-e45f-67a8-b901-234567890123", "name": "Active Client", "color": "#22c55e", "stage_order": 1, "is_default_status": true } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies/search": { "post": { "operationId": "searchCompanies", "summary": "Search companies", "description": "Advanced company search with filtering, sorting, and custom attribute filters.\n\n**Filters**: keywords (name/domain/LinkedIn), exact domain, exact linkedin_url, is_client, company_status_ids_included/excluded, owner_ids_included/excluded, relationships_included/excluded, list_ids_included/excluded, job_id, company_ids.\n\n**Custom attribute filters**: `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters`. Get attribute IDs and tag IDs from GET /v1/custom-fields/companies.\n\n**Sorting**: Pass `sort_by` with one of: `name`, `domain`, `status` (client status stage order), `date_of_last_engagement`, `created_at` (default), or `custom_` for any custom field. Pair with `sort_order` (`asc` or `desc`, default `desc`).\n\n**Include control**: Pass `include: [\"custom_fields\"]` to embed custom field values in each result.", "tags": [ "Companies" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesSearchBody" } } } }, "responses": { "200": { "description": "Companies found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesSearchResponse" }, "example": { "success": true, "data": [ { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme", "location": "San Francisco, CA", "is_client": true, "do_not_contact": true, "do_not_contact_metadata": { "reason": "Active client — protect from sourcing", "do_not_contact_added_by": "234e5678-e90a-12b3-c456-789012345678", "date_added": "2024-06-01T09:00:00Z", "last_updated_at": "2024-06-15T14:30:00Z", "last_updated_by": "234e5678-e90a-12b3-c456-789012345678", "expiration_date": "2024-09-15T00:00:00Z" }, "created_at": "2024-01-05T10:00:00Z", "updated_at": "2024-06-15T14:30:00Z", "updated_by": { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" }, "client_status": { "id": "789e0123-e45f-67a8-b901-234567890123", "name": "Active" }, "date_of_last_engagement": "2024-06-15T14:30:00Z", "enriched_company": { "id": "ec123456-7890-abcd-ef01-234567890abc", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme" }, "job_target_companies": [], "owners": [ { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" } ], "relationships": [], "custom_fields": [ { "attribute_id": "e5f6a7b8-c9d0-1234-efab-567890123456", "attribute_name": "Industry", "data_type": "single-select", "value": null, "tag": { "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", "name": "Technology" }, "team_member": null, "company": null } ] } ], "meta": { "total": 42, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies": { "post": { "operationId": "createOrUpdateCompany", "summary": "Create or update company", "description": "Create a new company record or update an existing one. Matching is done by LinkedIn URL, domain, or name. At least one of name, domain, or linkedin_url must be provided.\n\n**Custom fields**: Pass `custom_fields` to set custom attribute values. Get attribute definitions from GET /v1/custom-fields/companies.", "tags": [ "Companies" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreateOrUpdateRequest" } } } }, "responses": { "200": { "description": "Company created or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreateOrUpdateResponse" }, "example": { "success": true, "data": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme", "linkedin_id": 12345678, "location": "San Francisco, CA", "phone": "+1-555-0100", "description": "Leading technology solutions provider specializing in enterprise SaaS.", "is_client": true, "do_not_contact": true, "do_not_contact_metadata": { "reason": "Active client — protect from sourcing", "do_not_contact_added_by": "234e5678-e90a-12b3-c456-789012345678", "date_added": "2024-06-01T09:00:00Z", "last_updated_at": "2024-06-15T14:30:00Z", "last_updated_by": "234e5678-e90a-12b3-c456-789012345678", "expiration_date": "2024-09-15T00:00:00Z" }, "created_at": "2024-01-05T10:00:00Z", "updated_at": "2024-06-15T14:30:00Z", "updated_by": { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" }, "date_of_last_engagement": "2024-06-15T14:30:00Z", "client_status": { "id": "789e0123-e45f-67a8-b901-234567890123", "name": "Active" }, "enriched_company": { "id": "ec123456-7890-abcd-ef01-234567890abc", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme" }, "owners": [ { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" } ], "custom_fields": [ { "attribute_id": "e5f6a7b8-c9d0-1234-efab-567890123456", "attribute_name": "Industry", "data_type": "single-select", "value": null, "tag": { "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", "name": "Technology" }, "team_member": null, "company": null }, { "attribute_id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "attribute_name": "Account Owner", "data_type": "multi-team-member", "value": null, "tag": null, "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "company": null }, { "attribute_id": "b8c9d0e1-f2a3-4567-bcde-890123456789", "attribute_name": "Partner Companies", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies/{id}": { "patch": { "operationId": "updateCompany", "summary": "Update company", "description": "Update an existing company's information including name, domain, description, owners, custom field values, and do-not-contact status. Only provided fields are updated; omitted fields remain unchanged.\n\n**Owners**: Pass `owner_ids` to set the company owners. The list replaces all current owners; pass an empty array to remove every owner. Get team member IDs from GET /v1/team-members. To reassign owners across many companies, find them with POST /v1/companies/search (for example with `team_member_attribute_filters` or `owner_ids_included`) and update each one.\n\n**Do-not-contact**: Pass `do_not_contact: true` to flag the company (blocks outreach to anyone whose current company is this one) or `false` to clear it. Optionally include a `do_not_contact_reason` (free text) and `do_not_contact_expiration_date` (ISO 8601 timestamp). When the expiration field is omitted on a new do-not-contact flag, the team default from `auth_organization_settings.auto_dnc_company_on_search_days` is applied (days-from-now); pass `null` explicitly for an indefinite do-not-contact.", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyRequest" } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyResponse" }, "example": { "success": true, "data": { "message": "Company updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "get": { "operationId": "getCompanyById", "summary": "Get company by ID", "description": "Retrieve detailed information about a specific company including client status, owners, enriched data, and custom field values. Custom fields are included by default; pass `include=` (empty) for base fields only.", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company ID" } }, { "schema": { "type": "string", "description": "Comma-separated extra sections. Values: custom_fields. Default: custom_fields. Pass empty string for base fields only." }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Company fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyByIdResponse" }, "example": { "success": true, "data": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme", "linkedin_id": 12345678, "location": "San Francisco, CA", "phone": "+1-555-0100", "description": "Leading technology solutions provider specializing in enterprise SaaS.", "is_client": true, "do_not_contact": true, "do_not_contact_metadata": { "reason": "Active client — protect from sourcing", "do_not_contact_added_by": "234e5678-e90a-12b3-c456-789012345678", "date_added": "2024-06-01T09:00:00Z", "last_updated_at": "2024-06-15T14:30:00Z", "last_updated_by": "234e5678-e90a-12b3-c456-789012345678", "expiration_date": "2024-09-15T00:00:00Z" }, "created_at": "2024-01-05T10:00:00Z", "updated_at": "2024-06-15T14:30:00Z", "updated_by": { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" }, "date_of_last_engagement": "2024-06-15T14:30:00Z", "client_status": { "id": "789e0123-e45f-67a8-b901-234567890123", "name": "Active" }, "enriched_company": { "id": "ec123456-7890-abcd-ef01-234567890abc", "name": "Acme Corp", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme" }, "owners": [ { "id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith" } ], "custom_fields": [ { "attribute_id": "e5f6a7b8-c9d0-1234-efab-567890123456", "attribute_name": "Industry", "data_type": "single-select", "value": null, "tag": { "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", "name": "Technology" }, "team_member": null, "company": null }, { "attribute_id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "attribute_name": "Account Owner", "data_type": "multi-team-member", "value": null, "tag": null, "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "company": null }, { "attribute_id": "b8c9d0e1-f2a3-4567-bcde-890123456789", "attribute_name": "Partner Companies", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies/document-types": { "get": { "operationId": "listCompanyDocumentTypes", "summary": "List company document types", "description": "Returns every active company document type for the organization, ordered by name. No pagination — the full list is always returned.\n\nDocument types are configurable per organization, so the available keys differ between organizations. Call this to discover valid `document_types` values for `GET /v1/companies/{id}/documents` and valid `type` values when uploading a document.", "tags": [ "Companies" ], "responses": { "200": { "description": "Company document types fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentTypesResponse" }, "example": { "success": true, "data": [ { "type": "pitch_deck", "name": "Pitch Deck" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/companies/{id}/documents": { "get": { "operationId": "getCompanyDocuments", "summary": "Get company documents", "description": "Retrieve a paginated list of documents attached to a company, including pitch decks, client information, fee agreements, and legal documents. Stored files receive short-lived signed download URLs; re-fetch when a URL expires. Pass include_text=true to receive extracted plain-text content when it is available.", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company UUID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "default": false, "description": "When true, includes extracted plain-text content when available. Omit or pass false for metadata and links only." }, "required": false, "name": "include_text", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated document type keys to filter by. Seeded values: pitch_deck, legal, marketing, job_description, fee_agreement, offer_letter, client_information, compensation_information, other." }, "required": false, "name": "document_types", "in": "query" } ], "responses": { "200": { "description": "Documents fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentsResponse" }, "example": { "success": true, "data": [ { "created_at": "2026-08-06T13:00:00Z", "updated_at": "2026-08-06T13:00:00Z", "type": "pitch_deck", "title": "Acme Corp Pitch Deck.pdf", "link": "https://project.supabase.co/storage/v1/object/sign/company-documents/example", "text_content": "Acme Corp provides enterprise SaaS solutions.", "char_count": 43, "truncated": false } ], "meta": { "total": 1, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "uploadCompanyDocument", "summary": "Upload company document", "description": "Upload a document for a company. Supports two modes:\n\n**1. Direct file upload** (`Content-Type: multipart/form-data`):\nSend the file in a `file` field with `title` and `type` metadata fields. Allowed file types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB.\n\n**2. JSON body** (`Content-Type: application/json`):\nProvide a `file_url` — a publicly accessible HTTPS URL. The server downloads the file, validates it, and stores it.", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company UUID" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CompanyDocumentUploadMultipart" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentUploadRequest" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentUploadResponse" }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-4b89-8c01-345678901234", "created_at": "2026-08-06T13:00:00Z", "updated_at": "2026-08-06T13:00:00Z", "type": "pitch_deck", "title": "Acme Corp Pitch Deck.pdf", "link": "https://project.supabase.co/storage/v1/object/sign/company-documents/example" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-activities/types": { "get": { "operationId": "listCompanyActivityTypes", "summary": "List company activity types", "description": "Returns every activity type registered for the requesting team — built-in types (e.g. `secondary_note`, `call_note`, `meeting_note`, `email`) and any custom types defined under Settings → Activity Types. No pagination — the full list is returned in a single response.\n\n**When to use**: Call this before creating a company activity, or before filtering `GET /v1/company-activities` by `activity_types` / `excluded_activity_types`, so you know which keys are valid for the team.", "tags": [ "Company Activities" ], "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] }, { "type": "boolean" } ] }, "required": false, "name": "include_archived", "in": "query" } ], "responses": { "200": { "description": "Company activity types fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyActivityTypesResponse" }, "example": { "success": true, "data": [ { "type": "secondary_note", "name": "Note", "protected": true, "is_archived": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-activities": { "post": { "operationId": "createCompanyActivity", "summary": "Create company activity (note)", "description": "Log a new activity (note, call note, meeting note, email, etc.) on a company record. The activity_type must be a key registered for the team — discover valid keys with `GET /v1/company-activities/types`.", "tags": [ "Company Activities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCompanyActivityRequest" } } } }, "responses": { "201": { "description": "Company activity created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCompanyActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "organization_company_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "get": { "operationId": "listCompanyActivities", "summary": "List company activities", "description": "Returns a paginated list of activities (notes) attached to a company. Filtered by `organization_company_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys from GET /v1/company-activities/types). Sorted by `created_at` descending.", "tags": [ "Company Activities" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Company UUID to list activities for. Required." }, "required": true, "name": "organization_company_id", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to include (e.g. `secondary_note,call_note`). Discover valid keys via GET /v1/company-activities/types." }, "required": false, "name": "activity_types", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to exclude." }, "required": false, "name": "excluded_activity_types", "in": "query" } ], "responses": { "200": { "description": "Company activities fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyActivitiesResponse" }, "example": { "success": true, "data": [ { "id": "901e2345-e67f-89ab-cdef-456789012345", "organization_company_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "activity_content": "

Quarterly business review with finance team. Discussed Q3 hiring plans.

", "activity_raw_content": "Quarterly business review with finance team. Discussed Q3 hiring plans.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-activities/{id}": { "get": { "operationId": "getCompanyActivityById", "summary": "Get company activity by ID", "description": "Retrieve a single company activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member.", "tags": [ "Company Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company activity UUID." } } ], "responses": { "200": { "description": "Company activity fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompanyActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "organization_company_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "activity_content": "

Quarterly business review with finance team. Discussed Q3 hiring plans.

", "activity_raw_content": "Quarterly business review with finance team. Discussed Q3 hiring plans.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateCompanyActivityById", "summary": "Update company activity (note) by ID", "description": "Update the content of an existing company activity. Set `content_type` to `\"text\"` for plain text (auto-converted to HTML) or `\"html\"` for raw HTML input.", "tags": [ "Company Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Company activity UUID." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyActivityBody" } } } }, "responses": { "200": { "description": "Company activity updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "updated_at": "2024-03-15T12:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-insights": { "get": { "operationId": "listCompanyInsights", "summary": "List AI-extracted insights for a company", "description": "Returns AI-extracted, dismissable facts about a company that were derived from candidate notes and meeting transcripts.\n\n**Filters**: `organization_company_id` (required), `status` (default `active`), `category`.\n**Pagination**: `offset` and `limit` (max 100).\nSorted by `observation_date` desc, then `created_at` desc.", "tags": [ "Company Insights" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Required: company UUID whose insights to fetch." }, "required": true, "name": "organization_company_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "dismissed" ], "description": "Filter by status. Defaults to active only." }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "financials", "funding_ma", "team", "talent", "customers", "product", "tech", "gtm", "competitive", "culture", "other" ], "description": "Optional category filter." }, "required": false, "name": "category", "in": "query" } ], "responses": { "200": { "description": "Insights returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInsight" } }, "meta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total matching records across all pages." }, "offset": { "type": "number", "description": "Current pagination offset." }, "limit": { "type": "number", "description": "Page size used for this request." } }, "required": [ "total", "offset", "limit" ] } }, "required": [ "success", "data", "meta" ] }, "example": { "success": true, "data": [ { "id": "11111111-1111-1111-1111-111111111111", "organization_company_id": "22222222-2222-2222-2222-222222222222", "content": "May 2026 rev: $100M ARR", "category": "financials", "topic": "revenue", "observation_date": "2026-05-15", "status": "active", "is_user_edited": false, "source_activity_id": "33333333-3333-3333-3333-333333333333", "source_person_id": "44444444-4444-4444-4444-444444444444", "created_at": "2026-05-15T14:32:11.000Z", "updated_at": "2026-05-15T14:32:11.000Z" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-insights/{id}": { "patch": { "operationId": "updateCompanyInsight", "summary": "Edit content or dismiss/restore an insight", "description": "Update the fact text (sets `is_user_edited=true`) and/or set its status to `dismissed` (hides from search context and the UI) or `active`.", "tags": [ "Company Insights" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Insight UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New compact fact text. Sets is_user_edited=true." }, "status": { "type": "string", "enum": [ "active", "dismissed" ], "description": "Set to \"dismissed\" to hide, \"active\" to restore." } } } } } }, "responses": { "200": { "description": "Insight updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CompanyInsight" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": "11111111-1111-1111-1111-111111111111", "organization_company_id": "22222222-2222-2222-2222-222222222222", "content": "May 2026 rev: $100M ARR", "category": "financials", "topic": "revenue", "observation_date": "2026-05-15", "status": "active", "is_user_edited": false, "source_activity_id": "33333333-3333-3333-3333-333333333333", "source_person_id": "44444444-4444-4444-4444-444444444444", "created_at": "2026-05-15T14:32:11.000Z", "updated_at": "2026-05-15T14:32:11.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-insights/bulk-dismiss": { "post": { "operationId": "bulkDismissCompanyInsights", "summary": "Dismiss multiple insights at once", "description": "Marks all provided insight IDs as `dismissed`. Already-dismissed ones are ignored.", "tags": [ "Company Insights" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "insight_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 200, "description": "Insight UUIDs to dismiss (max 200)." } }, "required": [ "insight_ids" ] } } } }, "responses": { "200": { "description": "Insights dismissed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "dismissed_count": { "type": "number", "description": "Number of insights successfully dismissed." } }, "required": [ "dismissed_count" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "dismissed_count": 5 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/company-insights/trigger": { "post": { "operationId": "triggerCompanyInsightExtraction", "summary": "Manually extract insights from an activity", "description": "Runs the AI extraction pipeline on a specific activity (e.g. a secondary note or meeting transcript). Useful for re-running extraction or bypassing the cron.\n\n**Successful no-ops**: This endpoint returns `200` with `added_count: 0` when the activity is ineligible, the organization plan is not eligible, no linked companies or company-specific facts are found, or all extracted facts are duplicates. Some no-op responses have `ai_auto_update_id: null`; others reference an audit row marked as skipped.", "tags": [ "Company Insights" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "activity_id": { "type": "string", "format": "uuid", "description": "Activity (secondary_note or meeting_transcript) to extract insights from." } }, "required": [ "activity_id" ] } } } }, "responses": { "200": { "description": "Extraction completed or no eligible insights found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ai_auto_update_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Extraction audit row UUID. Null when extraction exits before an audit row is created; otherwise it can reference a completed, skipped, or failed audit." }, "added_count": { "type": "number", "description": "Number of new insights inserted. Zero is a successful no-op when the activity is ineligible, the plan is not eligible, no linked companies or facts are found, or all extracted facts are duplicates." } }, "required": [ "ai_auto_update_id", "added_count" ] } }, "required": [ "success", "data" ] }, "examples": { "insights_created": { "summary": "Insights created", "value": { "success": true, "data": { "ai_auto_update_id": "55555555-5555-5555-5555-555555555555", "added_count": 3 } } }, "no_op": { "summary": "Successful no-op", "value": { "success": true, "data": { "ai_auto_update_id": null, "added_count": 0 } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/custom-fields/persons": { "get": { "operationId": "getPersonCustomFieldDefinitions", "summary": "Get person custom field definitions", "description": "Retrieve custom attribute definitions for persons, including available tag options for select-type fields.\n\n**Scope**: By default, returns only global (person-level) definitions. Pass `job_id` to also include job-specific definitions for that job. Pass `list_id` to also include list-specific definitions. Both can be combined.\n\n**When to use**: Call this BEFORE using `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, or `team_member_attribute_filters` / `company_attribute_filters` in search endpoints (`POST /v1/persons/search`). You need the `attribute_id` and tag option IDs from this endpoint to construct those filters.\n\n**Example workflow**: To find persons tagged \"banking\" on a specific job → call this endpoint with `job_id` → find the \"Tags\" attribute → get its `id` as `attribute_id` → find the \"banking\" tag → get its `id` → pass both to `select_attribute_filters`.\n\n**Response**: Each definition includes `job_id` and `list_id` fields. Global attributes have both as null. Job-specific attributes have `job_id` set. List-specific attributes have `list_id` set.", "tags": [ "Custom Fields" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Job UUID. When provided, returns global person attributes PLUS job-specific attributes for this job. Without this parameter, only global person attributes are returned." }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "List UUID. When provided, returns global person attributes PLUS list-specific attributes for this list. Without this parameter, only global person attributes are returned." }, "required": false, "name": "list_id", "in": "query" } ], "responses": { "200": { "description": "Custom field definitions fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Seniority Level", "description": "Candidate seniority classification", "data_type": "single-select", "job_id": null, "list_id": null, "tags": [ { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Junior", "color": "#86efac", "description": null }, { "id": "f2e3d4c5-b6a7-8901-bcde-f12345678901", "name": "Mid", "color": "#93c5fd", "description": null }, { "id": "f3e4d5c6-b7a8-9012-cdef-g12345678902", "name": "Senior", "color": "#d8b4fe", "description": null } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Tags", "description": "General-purpose tags for categorization", "data_type": "multi-select", "job_id": null, "list_id": null, "tags": [ { "id": "a1b2c3d4-1234-5678-9abc-def012345678", "name": "Banking", "color": "#fde68a", "description": null }, { "id": "a2b3c4d5-2345-6789-0abc-def123456789", "name": "Fintech", "color": "#a5f3fc", "description": null }, { "id": "a3b4c5d6-3456-7890-1abc-def234567890", "name": "Referred", "color": "#fca5a5", "description": null } ] }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Years of Experience", "description": "Total years of professional experience", "data_type": "integer", "job_id": null, "list_id": null, "tags": [] }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Available From", "description": "Earliest start date", "data_type": "date", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Referred By", "description": "Companies that referred this record", "data_type": "multi-company", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Stage Rating", "description": "Candidate rating for this specific job", "data_type": "single-select", "job_id": "11223344-5566-7788-99aa-bbccddeeff00", "list_id": null, "tags": [ { "id": "b1c2d3e4-5678-9012-abcd-ef0123456789", "name": "A", "color": "#86efac", "description": null }, { "id": "b2c3d4e5-6789-0123-bcde-f01234567890", "name": "B", "color": "#fde68a", "description": null }, { "id": "b3c4d5e6-7890-1234-cdef-012345678901", "name": "C", "color": "#fca5a5", "description": null } ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/custom-fields/companies": { "get": { "operationId": "getCompanyCustomFieldDefinitions", "summary": "Get company custom field definitions", "description": "Retrieve custom attribute definitions for companies, including available tag options.\n\n**Scope**: By default, returns only global (company-level) definitions. Pass `job_id` to also include job-specific definitions for that job. Pass `list_id` to also include list-specific definitions. Optionally filter by `is_client` status. Both `job_id` and `list_id` can be combined.\n\n**When to use**: Call this to discover company-level attribute IDs and tag option IDs before using `current_company_attribute_filters` in person search endpoints.\n\n**Response**: Each definition includes `job_id` and `list_id` fields. Global attributes have both as null. Job-specific attributes have `job_id` set. List-specific attributes have `list_id` set.", "tags": [ "Custom Fields" ], "parameters": [ { "schema": { "type": "boolean", "description": "Filter definitions by client/non-client company type." }, "required": false, "name": "is_client", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Job UUID. When provided, returns global company attributes PLUS job-specific attributes for this job. Without this parameter, only global company attributes are returned." }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "List UUID. When provided, returns global company attributes PLUS list-specific attributes for this list. Without this parameter, only global company attributes are returned." }, "required": false, "name": "list_id", "in": "query" } ], "responses": { "200": { "description": "Custom field definitions fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Seniority Level", "description": "Candidate seniority classification", "data_type": "single-select", "job_id": null, "list_id": null, "tags": [ { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Junior", "color": "#86efac", "description": null }, { "id": "f2e3d4c5-b6a7-8901-bcde-f12345678901", "name": "Mid", "color": "#93c5fd", "description": null }, { "id": "f3e4d5c6-b7a8-9012-cdef-g12345678902", "name": "Senior", "color": "#d8b4fe", "description": null } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Tags", "description": "General-purpose tags for categorization", "data_type": "multi-select", "job_id": null, "list_id": null, "tags": [ { "id": "a1b2c3d4-1234-5678-9abc-def012345678", "name": "Banking", "color": "#fde68a", "description": null }, { "id": "a2b3c4d5-2345-6789-0abc-def123456789", "name": "Fintech", "color": "#a5f3fc", "description": null }, { "id": "a3b4c5d6-3456-7890-1abc-def234567890", "name": "Referred", "color": "#fca5a5", "description": null } ] }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Years of Experience", "description": "Total years of professional experience", "data_type": "integer", "job_id": null, "list_id": null, "tags": [] }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Available From", "description": "Earliest start date", "data_type": "date", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Referred By", "description": "Companies that referred this record", "data_type": "multi-company", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Stage Rating", "description": "Candidate rating for this specific job", "data_type": "single-select", "job_id": "11223344-5566-7788-99aa-bbccddeeff00", "list_id": null, "tags": [ { "id": "b1c2d3e4-5678-9012-abcd-ef0123456789", "name": "A", "color": "#86efac", "description": null }, { "id": "b2c3d4e5-6789-0123-bcde-f01234567890", "name": "B", "color": "#fde68a", "description": null }, { "id": "b3c4d5e6-7890-1234-cdef-012345678901", "name": "C", "color": "#fca5a5", "description": null } ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/custom-fields/jobs": { "get": { "operationId": "getJobCustomFieldDefinitions", "summary": "Get job custom field definitions", "description": "Retrieve custom attribute definitions for jobs, including available tag options.\n\n**When to use**: Call this to discover job-level attribute IDs needed when including `custom_fields` in job list/detail endpoints or sorting by `custom_` in search results.", "tags": [ "Custom Fields" ], "responses": { "200": { "description": "Custom field definitions fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Seniority Level", "description": "Candidate seniority classification", "data_type": "single-select", "job_id": null, "list_id": null, "tags": [ { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Junior", "color": "#86efac", "description": null }, { "id": "f2e3d4c5-b6a7-8901-bcde-f12345678901", "name": "Mid", "color": "#93c5fd", "description": null }, { "id": "f3e4d5c6-b7a8-9012-cdef-g12345678902", "name": "Senior", "color": "#d8b4fe", "description": null } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Tags", "description": "General-purpose tags for categorization", "data_type": "multi-select", "job_id": null, "list_id": null, "tags": [ { "id": "a1b2c3d4-1234-5678-9abc-def012345678", "name": "Banking", "color": "#fde68a", "description": null }, { "id": "a2b3c4d5-2345-6789-0abc-def123456789", "name": "Fintech", "color": "#a5f3fc", "description": null }, { "id": "a3b4c5d6-3456-7890-1abc-def234567890", "name": "Referred", "color": "#fca5a5", "description": null } ] }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Years of Experience", "description": "Total years of professional experience", "data_type": "integer", "job_id": null, "list_id": null, "tags": [] }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Available From", "description": "Earliest start date", "data_type": "date", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Referred By", "description": "Companies that referred this record", "data_type": "multi-company", "job_id": null, "list_id": null, "tags": [] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/custom-fields/deals": { "get": { "operationId": "getDealCustomFieldDefinitions", "summary": "Get deal custom field definitions", "description": "Retrieve custom attribute definitions for deals, including available tag options.\n\n**When to use**: Call this to discover deal-level attribute IDs needed for `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, or `team_member_attribute_filters` / `company_attribute_filters` in `POST /v1/deals/search`, or when setting `custom_fields` on deal create/update.", "tags": [ "Custom Fields" ], "responses": { "200": { "description": "Custom field definitions fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Seniority Level", "description": "Candidate seniority classification", "data_type": "single-select", "job_id": null, "list_id": null, "tags": [ { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Junior", "color": "#86efac", "description": null }, { "id": "f2e3d4c5-b6a7-8901-bcde-f12345678901", "name": "Mid", "color": "#93c5fd", "description": null }, { "id": "f3e4d5c6-b7a8-9012-cdef-g12345678902", "name": "Senior", "color": "#d8b4fe", "description": null } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Tags", "description": "General-purpose tags for categorization", "data_type": "multi-select", "job_id": null, "list_id": null, "tags": [ { "id": "a1b2c3d4-1234-5678-9abc-def012345678", "name": "Banking", "color": "#fde68a", "description": null }, { "id": "a2b3c4d5-2345-6789-0abc-def123456789", "name": "Fintech", "color": "#a5f3fc", "description": null }, { "id": "a3b4c5d6-3456-7890-1abc-def234567890", "name": "Referred", "color": "#fca5a5", "description": null } ] }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Years of Experience", "description": "Total years of professional experience", "data_type": "integer", "job_id": null, "list_id": null, "tags": [] }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Available From", "description": "Earliest start date", "data_type": "date", "job_id": null, "list_id": null, "tags": [] }, { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Referred By", "description": "Companies that referred this record", "data_type": "multi-company", "job_id": null, "list_id": null, "tags": [] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deal-activities": { "post": { "operationId": "createDealActivity", "summary": "Create deal activity (note)", "description": "Log a new activity (note, call note, meeting note, email, etc.) on a deal record. Standard activity_type keys: `secondary_note`, `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for deals.", "tags": [ "Deal Activities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDealActivityRequest" } } } }, "responses": { "201": { "description": "Deal activity created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDealActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "deal_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "call_note" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "get": { "operationId": "listDealActivities", "summary": "List deal activities", "description": "Returns a paginated list of activities (notes) attached to a deal. Filtered by `deal_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys). Sorted by `created_at` descending.", "tags": [ "Deal Activities" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Deal UUID to list activities for. Required." }, "required": true, "name": "deal_id", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to include (e.g. `secondary_note,call_note`)." }, "required": false, "name": "activity_types", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to exclude." }, "required": false, "name": "excluded_activity_types", "in": "query" } ], "responses": { "200": { "description": "Deal activities fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDealActivitiesResponse" }, "example": { "success": true, "data": [ { "id": "901e2345-e67f-89ab-cdef-456789012345", "deal_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "call_note", "activity_content": "

30-min call with VP Engineering. Aligned on scope and timeline.

", "activity_raw_content": "30-min call with VP Engineering. Aligned on scope and timeline.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deal-activities/{id}": { "get": { "operationId": "getDealActivityById", "summary": "Get deal activity by ID", "description": "Retrieve a single deal activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member.", "tags": [ "Deal Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Deal activity UUID." } } ], "responses": { "200": { "description": "Deal activity fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDealActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "deal_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "call_note", "activity_content": "

30-min call with VP Engineering. Aligned on scope and timeline.

", "activity_raw_content": "30-min call with VP Engineering. Aligned on scope and timeline.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateDealActivityById", "summary": "Update deal activity (note) by ID", "description": "Update the content of an existing deal activity. Set `content_type` to `\"text\"` for plain text (auto-converted to HTML) or `\"html\"` for raw HTML input.", "tags": [ "Deal Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Deal activity UUID." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDealActivityBody" } } } }, "responses": { "200": { "description": "Deal activity updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDealActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "updated_at": "2024-03-15T12:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deals/statuses": { "get": { "operationId": "listDealStatuses", "summary": "List deal statuses", "description": "Returns all deal statuses for the organization, ordered by stage_order. No pagination — the full list is always returned.\n\n**When to use**: Call this to discover available status IDs for `deal_status_ids_included` / `deal_status_ids_excluded` filters in `POST /v1/deals/search`, or for `deal_status_id` when creating/updating deals.", "tags": [ "Deals" ], "responses": { "200": { "description": "Deal statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealStatusesListResponse" }, "example": { "success": true, "data": [ { "id": "ccc33333-dddd-eeee-ffff-000000003333", "name": "Proposal Sent", "color": "#3b82f6", "stage_order": 2, "status_type": "active", "is_default_status": false, "default_win_probability": 40, "rotting_days": null, "effective_rotting_days": 14 } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deals/search": { "post": { "operationId": "searchDeals", "summary": "Search deals", "description": "Search and filter deals with pagination and sorting using the deals_list_query RPC.\n\n**Filters**: `keywords` (name + company search), `deal_status_ids_included`/`excluded`, `owner_ids_included`/`excluded`, `show_open_deals_only`, `show_archived`, `closed_date_filter`, `open_date_filter`, and custom attribute filters (`select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters`).\n\n**Sorting**: `name`, `amount`, `win_probability`, `company`, `status`, `closed_date`, `open_date`, `last_contacted_at`, `created_at`, or `custom_` for custom attribute sorting.\n\n**Include**: Pass `[\"custom_fields\"]` and/or `[\"client_contacts\"]` to embed those sections. `client_contacts` are omitted unless explicitly requested.\n\nFor API-key callers, `compensation` and `compensation_currency_code` require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`. `next_task`, `open_task_count` and `needs_attention` also require `tasks:read`.", "tags": [ "Deals" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsSearchBody" } } } }, "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsSearchResponse" }, "example": { "success": true, "data": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Acme Corp Staffing Agreement", "amount": 150000, "currency_code": "USD", "compensation": 750000, "compensation_currency_code": "USD", "pricing_rate": 20, "win_probability": 75, "closed_date": "2024-06-30T00:00:00Z", "open_date": "2024-01-15", "last_contacted_at": "2024-05-20T14:30:00Z", "deal_status": { "id": "ccc33333-dddd-eeee-ffff-000000003333", "name": "Proposal Sent" }, "created_at": "2024-01-15T10:00:00Z", "client_name": "Acme Corp", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "deal_lost_reason_id": null, "deal_lost_reason_text": null, "deal_lost_reason": null, "deal_won_reason_id": "66666666-7777-8888-9999-aaaaaaaaaaaa", "deal_won_reason_text": "Client chose us because of prior executive-search success.", "deal_won_reason": { "id": "66666666-7777-8888-9999-aaaaaaaaaaaa", "reason": "Strong relationship" }, "next_task": { "id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "title": "Follow-up call", "task_type": "call", "due_date": "2024-05-22T15:00:00Z" }, "open_task_count": 2, "stage_entered_at": "2024-05-01T09:00:00Z", "days_in_stage": 21, "is_rotting": true, "needs_attention": true, "owners": [ { "id": "ddd44444-eeee-ffff-0000-111111114444", "name": "Jane Smith" } ], "custom_fields": [ { "attribute_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "attribute_name": "Deal Priority", "data_type": "single-select", "value": null, "tag": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "name": "Acme Corp" } } ] } ], "meta": { "total": 100, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deals/{id}": { "get": { "operationId": "getDealById", "summary": "Get deal by ID", "description": "Retrieve a single deal by UUID, including won/lost reasons and notes, with optional custom field values.\n\nArchived deals are returned the same as active ones. Check `is_archived` on the response.\n\n`client_contacts` are always included (empty array when none are linked).\n\n**Include**: By default, `custom_fields` are included. Pass `include=` (empty) for base fields only.\n\nFor API-key callers, `compensation` and `compensation_currency_code` require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`.", "tags": [ "Deals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Deal UUID" } }, { "schema": { "type": "string", "description": "Comma-separated extra sections. Values: custom_fields. Default: custom_fields. Pass empty string for base fields only. Won/lost reasons, notes, and client_contacts are always included in the base deal detail." }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Deal fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealByIdResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Acme Corp Staffing Agreement", "amount": 150000, "currency_code": "USD", "compensation": 750000, "compensation_currency_code": "USD", "pricing_rate": 20, "win_probability": 75, "description": "Annual staffing contract for engineering positions.", "closed_date": "2024-06-30T00:00:00Z", "open_date": "2024-01-15", "deal_lost_reason_id": null, "deal_lost_reason_text": null, "deal_lost_reason": null, "deal_won_reason_id": "66666666-7777-8888-9999-aaaaaaaaaaaa", "deal_won_reason_text": "Client chose us because of prior executive-search success.", "deal_won_reason": { "id": "66666666-7777-8888-9999-aaaaaaaaaaaa", "reason": "Strong relationship" }, "referred_by": "fff66666-0000-1111-2222-333333336666", "job_ids": [ "eee55555-ffff-0000-1111-222222225555" ], "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "client_name": "Acme Corp", "deal_status": { "id": "ccc33333-dddd-eeee-ffff-000000003333", "name": "Proposal Sent" }, "is_archived": false, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-02-01T12:00:00Z", "owners": [ { "id": "ddd44444-eeee-ffff-0000-111111114444", "name": "Jane Smith" } ], "client_contacts": [ { "id": "ab12cd34-ef56-7890-ab12-cd34ef567890", "person_id": "fff66666-0000-1111-2222-333333336666", "name": "Alex Rivera", "image_url": "https://example.com/alex.jpg", "job_title": "VP of Engineering", "email": "alex.rivera@acme.com", "phone": "+1-555-0100" } ], "custom_fields": [ { "attribute_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "attribute_name": "Deal Priority", "data_type": "single-select", "value": null, "tag": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "name": "Acme Corp" } } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateDeal", "summary": "Update deal", "description": "Update an existing deal, including won/lost reason IDs and notes. Only provided fields are modified; omitted fields remain unchanged.\n\nArchived deals can be updated. Pass `is_archived: false` to unarchive, or `is_archived: true` to archive. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident.", "tags": [ "Deals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Deal UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdateRequest" } } } }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdateResponse" }, "example": { "success": true, "data": { "message": "Deal updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteDeal", "summary": "Archive deal", "description": "Archive a deal by marking it as deleted. The record is retained and can be found with the `show_archived` search filter, fetched by ID, or unarchived with `PATCH /v1/deals/{id}` (`is_archived: false`).", "tags": [ "Deals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Deal UUID" } } ], "responses": { "200": { "description": "Deal archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Deal archived successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/deals": { "post": { "operationId": "createDeal", "summary": "Create deal", "description": "Create a new deal record. Provide `client_linkedin_url` to automatically look up or create the client company when `client_id` is not known.\n\nFor API-key callers, `compensation` and `compensation_currency_code` on the response require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`.", "tags": [ "Deals" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealCreateRequest" } } } }, "responses": { "201": { "description": "Deal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealCreateResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Acme Corp Staffing Agreement", "amount": 150000, "currency_code": "USD", "compensation": 750000, "compensation_currency_code": "USD", "pricing_rate": 20, "win_probability": 75, "deal_status_id": "ccc33333-dddd-eeee-ffff-000000003333", "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "job_ids": [ "eee55555-ffff-0000-1111-222222225555" ], "owner_ids": [ "ddd44444-eeee-ffff-0000-111111114444" ], "client_contact_ids": [ "ab12cd34-ef56-7890-ab12-cd34ef567890" ], "open_date": "2024-01-15", "created_at": "2024-01-15T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/fee-statuses": { "get": { "operationId": "listFeeStatuses", "summary": "List fee statuses", "description": "Returns every fee status of the workspace (the statuses of retainers, milestones, placements and retainer packs), ordered by position. No pagination: the full list is always returned.\n\n**When to use**: get a `fee_status_id` for `POST /v1/retainer-packs` or `PATCH /v1/retainer-packs/{id}`.\n\n**Access**: Everyone in the workspace. API keys need the `fees:read` scope.", "tags": [ "Retainer Packs" ], "responses": { "200": { "description": "Fee statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeStatusesListResponse" }, "example": { "success": true, "data": [ { "id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8b", "name": "Pending", "status_type": "pending", "color": "#f59e0b", "position": 0, "is_default": true }, { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9c", "name": "Invoiced", "status_type": "invoiced", "color": "#3b82f6", "position": 1, "is_default": false }, { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e", "position": 2, "is_default": false }, { "id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0d", "name": "Cancelled", "status_type": "cancelled", "color": "#6b7280", "position": 3, "is_default": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/job-activities": { "post": { "operationId": "createJobActivity", "summary": "Create job activity (note)", "description": "Log a new activity (note, call note, meeting note, email, etc.) on a job record. Standard activity_type keys: `secondary_note`, `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for jobs.", "tags": [ "Job Activities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddJobActivityRequest" } } } }, "responses": { "201": { "description": "Job activity created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddJobActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "job_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "get": { "operationId": "listJobActivities", "summary": "List job activities", "description": "Returns a paginated list of activities (notes) attached to a job. Filtered by `job_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys). Sorted by `created_at` descending.", "tags": [ "Job Activities" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Job UUID to list activities for. Required." }, "required": true, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to include (e.g. `secondary_note,call_note`)." }, "required": false, "name": "activity_types", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated activity type keys to exclude." }, "required": false, "name": "excluded_activity_types", "in": "query" } ], "responses": { "200": { "description": "Job activities fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobActivitiesResponse" }, "example": { "success": true, "data": [ { "id": "901e2345-e67f-89ab-cdef-456789012345", "job_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "activity_content": "

Hiring manager kickoff. Aligned on must-have requirements and pipeline strategy.

", "activity_raw_content": "Hiring manager kickoff. Aligned on must-have requirements and pipeline strategy.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/job-activities/{id}": { "get": { "operationId": "getJobActivityById", "summary": "Get job activity by ID", "description": "Retrieve a single job activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member.", "tags": [ "Job Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job activity UUID." } } ], "responses": { "200": { "description": "Job activity fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJobActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "job_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "activity_content": "

Hiring manager kickoff. Aligned on must-have requirements and pipeline strategy.

", "activity_raw_content": "Hiring manager kickoff. Aligned on must-have requirements and pipeline strategy.", "is_starred": false, "created_by": { "id": "7d57bf3f-b470-48c0-ac98-a3f75b817209", "first_name": "Pranav", "last_name": "Patel" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateJobActivityById", "summary": "Update job activity (note) by ID", "description": "Update the content of an existing job activity. Set `content_type` to `\"text\"` for plain text (auto-converted to HTML) or `\"html\"` for raw HTML input.", "tags": [ "Job Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job activity UUID." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobActivityBody" } } } }, "responses": { "200": { "description": "Job activity updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89ab-cdef-456789012345", "updated_at": "2024-03-15T12:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/job-offers/statuses": { "get": { "operationId": "listJobOfferStatuses", "summary": "List job offer statuses", "description": "Returns all job offer statuses for the organization, ordered by stage_order. No pagination — the full list is always returned.\n\n**When to use**: Call this to discover status IDs for the `job_offer_status_id` filter in `GET /v1/job-offers`.\n\n**Access**: Session and OAuth callers need `org:reports:offer_tracking` (`org:admin` bypasses). API keys need the `offers:read` scope.", "tags": [ "Job Offers" ], "responses": { "200": { "description": "Job offer statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOfferStatusesListResponse" }, "example": { "success": true, "data": [ { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Accepted", "color": "#22c55e", "stage_order": 3, "status_type": "accepted", "is_default_status": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Caller lacks permission to view job offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/job-offers": { "get": { "operationId": "listJobOffers", "summary": "List job offers", "description": "Retrieve a paginated list of offers extended to candidates, with the job, client company, person, status, key dates, offer compensation, owners (team members credited on the offer), and client contacts attached to the offer.\n\n**Filters**: `job_id`, `candidate_id`, `person_id`, `job_offer_status_id`, `status_type` (pending, accepted, rejected, rescinded), and `extended_date_after` / `extended_date_before` (ISO 8601 date range).\n\n**Sorting**: `sort_by` (created_at, updated_at, extended_date, accepted_date, candidate_start_date) with `sort_order` (asc/desc, default desc).\n\n**Pagination**: Use `offset` and `limit` query params (max 100 per page).\n\n**Access**: Session and OAuth callers need `org:reports:offer_tracking` (`org:admin` bypasses). API keys need the `offers:read` scope. Compensation fields (`compensation_*`, `bonus_type`, equity grants, `relocation_bonus`, `sign_on_bonus`, `total_estimated_compensation`) are omitted for API keys without `compensation:read`.\n\nOffers on jobs the caller cannot access are not returned.", "tags": [ "Job Offers" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only return offers for this job." }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only return offers for this candidate record (a person on a specific job)." }, "required": false, "name": "candidate_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only return offers made to this person, across all jobs." }, "required": false, "name": "person_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only return offers in this status. Get status IDs from GET /v1/job-offers/statuses." }, "required": false, "name": "job_offer_status_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "accepted", "rejected", "rescinded" ], "description": "Only return offers whose status belongs to this lifecycle category: `pending`, `accepted`, `rejected`, or `rescinded`." }, "required": false, "name": "status_type", "in": "query" }, { "schema": { "type": "string", "description": "Return offers extended at or after this timestamp (ISO 8601). Example: `2026-04-01T00:00:00Z`." }, "required": false, "name": "extended_date_after", "in": "query" }, { "schema": { "type": "string", "description": "Return offers extended at or before this timestamp (ISO 8601). Example: `2026-04-30T23:59:59Z`." }, "required": false, "name": "extended_date_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at", "extended_date", "accepted_date", "candidate_start_date" ], "default": "created_at", "description": "Column to sort results by. Defaults to `created_at`. Offers with no value for the chosen date sort last.\n- `created_at` — when the offer was recorded\n- `updated_at` — when the offer was last changed\n- `extended_date` — when the offer was extended to the candidate\n- `accepted_date` — when the candidate accepted\n- `candidate_start_date` — when the candidate is expected to start" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (newest first)." }, "required": false, "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "Job offers fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOffersListResponse" }, "example": { "success": true, "data": [ { "id": "7e8f9012-3456-4789-a012-bcdef0123456", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_name": "VP of Engineering", "job_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "job_company_name": "Acme Corp", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Accepted", "color": "#22c55e", "status_type": "accepted" }, "owners": [ { "id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "name": "Jane Smith", "first_name": "Jane", "last_name": "Smith", "image_url": "https://img.clerk.com/jane-smith.png" } ], "client_contacts": [ { "id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "person_id": "8b9c0d1e-2f3a-4b4c-9d6e-7f8a9b0c1d2e", "name": "Morgan Patel", "first_name": "Morgan", "last_name": "Patel", "image_url": "https://media.example.com/morgan-patel.jpg" } ], "extended_date": "2026-04-02T00:00:00.000Z", "accepted_date": "2026-04-09T00:00:00.000Z", "candidate_start_date": "2026-05-04T00:00:00.000Z", "compensation_currency": "USD", "compensation_base": 285000, "compensation_bonus": 20, "bonus_type": "percent", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": 0.25, "initial_equity_grant_amount": 400000, "relocation_bonus": 15000, "sign_on_bonus": 25000, "total_estimated_compensation": 392000, "note": "Accepted after a second-round counter on base.", "created_at": "2026-04-02T15:20:00.000Z", "updated_at": "2026-04-09T18:05:00.000Z" } ], "meta": { "total": 12, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Caller lacks permission to view job offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs": { "get": { "operationId": "listJobs", "summary": "List jobs (deprecated)", "deprecated": true, "description": "**Deprecated** — Use `POST /v1/jobs/search` instead for full filtering, sorting, and vector search.\n\nRetrieve a paginated list of jobs with team members and candidate counts. Optionally filter by archive status (`is_archived`) and/or team member and role (e.g. \"Executive Sponsor\").\n\n**Include control**: The `include` query param accepts a comma-separated list. Allowed values: `custom_fields`, `linked_deals`, `fees`, `client_contacts`, `share_links`, `job_status_changes`. When omitted, no extra sections are returned. `job_status_changes` embeds the recorded status history on each job, oldest first. For API-key callers, `linked_deals` requires `deals:read` and `fees` requires `compensation:read`; inaccessible sections are omitted.\n\n**Note**: This endpoint does NOT return pipeline stages. To get a job's pipeline stage IDs and names (needed for stage-based filtering in person search), use `GET /v1/jobs/{id}` instead.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter by archive status. Omit for all jobs, true for archived only, false for active only." }, "required": false, "name": "is_archived", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Filter to jobs where this team member is assigned. Get IDs from GET /v1/team-members." }, "required": false, "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by team member email. Fallback when team_member_id is not available." }, "required": false, "name": "team_member_email", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Filter to jobs that have a member with this role. Get role IDs from GET /v1/jobs/team-member-roles." }, "required": false, "name": "team_member_role_id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by role name (e.g. \"Executive Sponsor\"). Fallback when team_member_role_id is not available." }, "required": false, "name": "team_member_role_name", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated extra sections. Values: custom_fields, linked_deals, fees, client_contacts, share_links, job_status_changes. Omit for base fields only. job_status_changes embeds the recorded status history, oldest first. For API-key callers, linked_deals requires deals:read and fees requires compensation:read; inaccessible sections are omitted." }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Jobs fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Senior Software Engineer", "created_at": "2024-01-10T09:00:00Z", "is_archived": false, "client_company_name": "StartupXYZ", "client_company_id": "456e7890-e12b-34d5-a678-901234567890", "client_company_domain": "startupxyz.com", "client_company_linkedin_url": "https://www.linkedin.com/company/startupxyz", "job_status_name": "Active", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_type": "in_progress", "candidate_count": 12, "location": "San Francisco, CA", "primary_url": "https://startupxyz.com/careers/senior-swe", "job_function": "Engineering", "open_date": "2024-01-01", "end_date": null, "currency_code": "USD", "salary_range": "[150000,200001)", "salary_min": 150000, "salary_max": 200000, "salary_details": "+ 0.5% equity, signing bonus negotiable", "billing_contact_name": "Sarah Chen", "billing_contact_email": "sarah.chen@startupxyz.com", "fee": 25000, "description": "We are looking for a Senior Software Engineer to join our platform team...", "team_members": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "email": "jane@company.com", "first_name": "Jane", "last_name": "Smith", "role_id": "345e6789-e01b-23c4-d567-890123456789", "role_name": "Team Lead" }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "email": "bob@company.com", "first_name": "Bob", "last_name": "Johnson", "role_id": "456e7890-f12b-34d5-e678-901234567890", "role_name": "Executive Sponsor" } ], "client_contacts": [ { "id": "c1d2e3f4-a5b6-7890-cdef-123456789012", "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Maria Gonzalez" } ], "share_links": [ { "id": "client-pipeline-abc123", "url": "https://stardex.com/share/startupxyz/client-pipeline-abc123", "title": "Client pipeline", "created_at": "2024-01-12T14:30:00Z", "requires_email_verification": true, "keep_active_when_job_closed": false } ], "linked_deals": [ { "deal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deal_job_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "StartupXYZ — Senior SWE retained search", "amount": 35000, "currency_code": "USD", "deal_status_id": "7201a0b8-e63c-4d8f-899d-78cdd62b5c38", "deal_status_name": "Qualified", "deal_status_color": "#10B981" } ], "fees": { "retainer": { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_type": "percentage", "fee_base": "first_year_salary", "fee_percentage": 25, "projected_fee": 50000, "estimated_compensation": 200000, "installment_count": 3, "final_payment_type": "on_placement", "currency_code": "USD" }, "fee_events": [ { "id": "f6a7b8c9-d0e1-2345-f012-456789012345", "type": "retainer", "label": "Engagement fee", "amount": 16666.67, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": 1, "start_date": "2024-01-05", "expected_date": "2024-01-10", "actual_payment_date": "2024-01-11", "candidate_id": null, "offer_id": null, "retainer_id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_status_id": "a7b8c9d0-e1f2-3456-0123-567890123456", "fee_status_name": "Paid", "fee_status_color": "#10B981", "fee_status_type": "paid", "linked_retainer_pack_id": null, "claimed_pack_retainer_id": null, "pack_retainer_amount": null }, { "id": "b8c9d0e1-f2a3-4567-1234-678901234567", "type": "placement", "label": "Placement — Jane Smith", "amount": 21333.33, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": null, "start_date": null, "expected_date": "2024-03-15", "actual_payment_date": null, "candidate_id": "234e5678-e90a-12b3-c456-789012345678", "offer_id": "c9d0e1f2-a3b4-5678-2345-789012345678", "retainer_id": null, "fee_status_id": "d0e1f2a3-b4c5-6789-3456-890123456789", "fee_status_name": "Invoiced", "fee_status_color": "#3B82F6", "fee_status_type": "invoiced", "linked_retainer_pack_id": "2b3c4d5e-6f70-4812-9a3b-c4d5e6f70812", "claimed_pack_retainer_id": "3c4d5e6f-7081-4923-ab4c-d5e6f7081923", "pack_retainer_amount": 12000 } ], "total_placement_fee": 50000 }, "job_status_changes": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "job_status_id": "111e2222-e33f-44a5-b666-777888999000", "job_status_name": "Not Started", "job_status_type": "not_started", "entered_at": "2024-01-01T12:00:00Z", "exited_at": "2024-01-10T09:00:00Z", "created_at": "2024-01-01T12:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": null }, { "id": "a2b3c4d5-e6f7-8901-bcde-f12345678901", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_name": "Active", "job_status_type": "in_progress", "entered_at": "2024-01-10T09:00:00Z", "exited_at": null, "created_at": "2024-01-10T09:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": "Kickoff complete" } ], "custom_fields": [ { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "attribute_name": "Priority", "data_type": "single-select", "value": null, "tag": { "id": "d4e5f6a7-b8c9-0123-defg-234567890123", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "attribute_name": "Sponsor", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ] } ], "meta": { "total": 25, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "createJob", "summary": "Create job", "description": "Create a new job with company association, pipeline template, and team member assignments. The company will be matched or created automatically based on the identifiers provided. Optionally assign `job_status_id` from GET /v1/jobs/statuses (defaults to the team default status). Optionally link existing deals by passing deal_ids — each deal must belong to the same team (resolve IDs via POST /v1/deals/search). Optionally link existing client contacts by passing client_contact_ids — each contact must belong to the same team (resolve IDs via GET /v1/client-contacts). Pass `include=job_status_changes` to embed the recorded status history on the created job, oldest first. Background AI tasks (candidate search, criteria generation) are triggered after creation. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "description": "Comma-separated extra sections. Value: job_status_changes. Embeds the recorded status history on the job, oldest first. Omit to leave status history off the response. Pipeline stages, custom fields, client contacts, share links, linked deals, and fees are always returned on GET /v1/jobs/{id} and on the create response." }, "required": false, "name": "include", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "201": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Senior Software Engineer", "created_at": "2024-01-10T09:00:00Z", "is_archived": false, "client_company_name": "StartupXYZ", "client_company_id": "456e7890-e12b-34d5-a678-901234567890", "client_company_domain": "startupxyz.com", "client_company_linkedin_url": "https://www.linkedin.com/company/startupxyz", "job_status_name": "Active", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_type": "in_progress", "candidate_count": 12, "location": "San Francisco, CA", "primary_url": "https://startupxyz.com/careers/senior-swe", "job_function": "Engineering", "open_date": "2024-01-01", "end_date": null, "currency_code": "USD", "salary_range": "[150000,200001)", "salary_min": 150000, "salary_max": 200000, "salary_details": "+ 0.5% equity, signing bonus negotiable", "billing_contact_name": "Sarah Chen", "billing_contact_email": "sarah.chen@startupxyz.com", "fee": 25000, "description": "We are looking for a Senior Software Engineer to join our platform team...", "team_members": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "email": "jane@company.com", "first_name": "Jane", "last_name": "Smith", "role_id": "345e6789-e01b-23c4-d567-890123456789", "role_name": "Team Lead" }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "email": "bob@company.com", "first_name": "Bob", "last_name": "Johnson", "role_id": "456e7890-f12b-34d5-e678-901234567890", "role_name": "Executive Sponsor" } ], "client_contacts": [ { "id": "c1d2e3f4-a5b6-7890-cdef-123456789012", "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Maria Gonzalez" } ], "share_links": [ { "id": "client-pipeline-abc123", "url": "https://stardex.com/share/startupxyz/client-pipeline-abc123", "title": "Client pipeline", "created_at": "2024-01-12T14:30:00Z", "requires_email_verification": true, "keep_active_when_job_closed": false } ], "linked_deals": [ { "deal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deal_job_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "StartupXYZ — Senior SWE retained search", "amount": 35000, "currency_code": "USD", "deal_status_id": "7201a0b8-e63c-4d8f-899d-78cdd62b5c38", "deal_status_name": "Qualified", "deal_status_color": "#10B981" } ], "fees": { "retainer": { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_type": "percentage", "fee_base": "first_year_salary", "fee_percentage": 25, "projected_fee": 50000, "estimated_compensation": 200000, "installment_count": 3, "final_payment_type": "on_placement", "currency_code": "USD" }, "fee_events": [ { "id": "f6a7b8c9-d0e1-2345-f012-456789012345", "type": "retainer", "label": "Engagement fee", "amount": 16666.67, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": 1, "start_date": "2024-01-05", "expected_date": "2024-01-10", "actual_payment_date": "2024-01-11", "candidate_id": null, "offer_id": null, "retainer_id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_status_id": "a7b8c9d0-e1f2-3456-0123-567890123456", "fee_status_name": "Paid", "fee_status_color": "#10B981", "fee_status_type": "paid", "linked_retainer_pack_id": null, "claimed_pack_retainer_id": null, "pack_retainer_amount": null }, { "id": "b8c9d0e1-f2a3-4567-1234-678901234567", "type": "placement", "label": "Placement — Jane Smith", "amount": 21333.33, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": null, "start_date": null, "expected_date": "2024-03-15", "actual_payment_date": null, "candidate_id": "234e5678-e90a-12b3-c456-789012345678", "offer_id": "c9d0e1f2-a3b4-5678-2345-789012345678", "retainer_id": null, "fee_status_id": "d0e1f2a3-b4c5-6789-3456-890123456789", "fee_status_name": "Invoiced", "fee_status_color": "#3B82F6", "fee_status_type": "invoiced", "linked_retainer_pack_id": "2b3c4d5e-6f70-4812-9a3b-c4d5e6f70812", "claimed_pack_retainer_id": "3c4d5e6f-7081-4923-ab4c-d5e6f7081923", "pack_retainer_amount": 12000 } ], "total_placement_fee": 50000 }, "job_status_changes": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "job_status_id": "111e2222-e33f-44a5-b666-777888999000", "job_status_name": "Not Started", "job_status_type": "not_started", "entered_at": "2024-01-01T12:00:00Z", "exited_at": "2024-01-10T09:00:00Z", "created_at": "2024-01-01T12:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": null }, { "id": "a2b3c4d5-e6f7-8901-bcde-f12345678901", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_name": "Active", "job_status_type": "in_progress", "entered_at": "2024-01-10T09:00:00Z", "exited_at": null, "created_at": "2024-01-10T09:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": "Kickoff complete" } ], "custom_fields": [ { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "attribute_name": "Priority", "data_type": "single-select", "value": null, "tag": { "id": "d4e5f6a7-b8c9-0123-defg-234567890123", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "attribute_name": "Sponsor", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ], "referral_partners": [ { "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Priya Natarajan", "title": "Managing Partner", "image_url": "https://example.com/priya-natarajan.png", "company_id": "678e9012-a34b-56c7-d890-123456789abc", "company_name": "Northwind Ventures", "default_split_percentage": 10, "default_mode": "off_the_top", "created_at": "2024-01-12T15:00:00Z" }, { "client_contact_id": "f4a5b6c7-d8e9-0123-fabc-456789012345", "person_id": "a5b6c7d8-e9f0-1234-abcd-567890123456", "name": "Tom Becker", "title": "Board Advisor", "image_url": null, "company_id": "456e7890-e12b-34d5-a678-901234567890", "company_name": "StartupXYZ", "default_split_percentage": null, "default_mode": "team_pool", "created_at": "2024-01-20T09:30:00Z" } ], "pack_retainer_split": [ { "team_member_id": "456e7890-a12b-34c5-d678-901234567890", "team_member_name": "Theo Martin", "role": "Sales", "split_percentage": 30 }, { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "role": null, "split_percentage": 35 }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "team_member_name": "Bob Johnson", "role": null, "split_percentage": 35 } ], "pipeline_stages": [ { "id": "345e6789-e01b-23c4-d567-890123456789", "job_pipeline_stage_id": "a12e3456-b78c-49d0-e123-456789012345", "name": "Application Review", "stage_order": 1000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false }, { "id": "456e7890-f12b-34d5-e678-901234567890", "job_pipeline_stage_id": "b23e4567-c89d-40e1-f234-567890123456", "name": "Phone Screen", "stage_order": 2000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "567e8901-e23c-45d6-e789-012345678901", "job_pipeline_stage_id": "c34e5678-d90e-41f2-a345-678901234567", "name": "Technical Interview", "stage_order": 2500, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "901e2345-b67c-89d0-e123-456789012345", "job_pipeline_stage_id": "d45e6789-e01f-42a3-b456-789012345678", "name": "Take Home Assessment", "stage_order": 2750, "is_archived": true, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "678e9012-f34d-56e7-f890-123456789012", "job_pipeline_stage_id": "e56e7890-f12a-43b4-c567-890123456789", "name": "Offer", "stage_order": 3000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": true, "is_placement_stage": false }, { "id": "789e0123-a45b-67c8-d901-234567890123", "job_pipeline_stage_id": "f67e8901-a23b-44c5-d678-901234567890", "name": "Rejected", "stage_order": 9000, "is_archived": false, "is_rejection_stage": true, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/search": { "post": { "operationId": "searchJobs", "summary": "Search jobs", "description": "Advanced job search with filtering, sorting, and vector search. Supports all filter types: keywords, location, job status, companies, team members/roles, custom attributes (select, numeric, date, team member), and semantic vector search.\n\n**AI AGENTS — Use `vector_search` if the user is inquiring about roles by title or title and company. Do not use `keywords`.**\nJob titles have many equivalent forms (\"VP of Engineering\", \"VP Engineering\", \"Engineering VP\", \"Head of Engineering\") — keywords will silently miss them . Vector search handles all variants automatically.\nThe exception: a verbatim job ID/code lookup where you need an exact internal reference (e.g. \"find the jobID 1234\").\n\n**Archive filter (`is_archived`)**: Omit to include both active and archived jobs (recommended for similar past searches, comps, pitch prep, company/sector history). Pass `false` for active jobs only; `true` for archived only. Always surface archive/status in answers.\n\n**Vector search**: Pass `vector_search` with a text query (min 5 chars) for AI-powered semantic search.\n\n**Date range filters**: Use `created_at_gte`/`created_at_lte` and `updated_at_gte`/`updated_at_lte` to filter by creation or modification timestamps.\n\n**Custom attribute filters**: Use `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters` for custom field filtering.\n\n**Include control**: Pass `include: [\"custom_fields\", \"linked_deals\", \"fees\", \"client_contacts\", \"share_links\", \"pipeline_stages\", \"job_status_changes\"]` to embed custom field values, linked deals, fee & placement data, client contacts, active share links, pipeline stages, and/or the recorded status history in each job. `job_status_changes` is ordered oldest first. For API-key callers, `linked_deals` requires `deals:read` and `fees` requires `compensation:read`; inaccessible sections are omitted.\n\nAI AGENTS — Result processing: After receiving results, reason and process them before presenting to the user. Only show jobs where the title genuinely matches what the user asked for. For example, if the user asks for \"VP of Engineering\" roles, exclude results like \"VP Consumer Electronics\" or \"SVP Sales Engineering\" — these are not engineering leadership roles. Show relevant results rather than regurgitating everything the vector search returns.", "tags": [ "Jobs" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsSearchBody" } } } }, "responses": { "200": { "description": "Jobs found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsSearchResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Senior Software Engineer", "created_at": "2024-01-10T09:00:00Z", "is_archived": false, "client_company_name": "StartupXYZ", "client_company_id": "456e7890-e12b-34d5-a678-901234567890", "client_company_domain": "startupxyz.com", "client_company_linkedin_url": "https://www.linkedin.com/company/startupxyz", "job_status_name": "Active", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_type": "in_progress", "candidate_count": 12, "location": "San Francisco, CA", "primary_url": "https://startupxyz.com/careers/senior-swe", "job_function": "Engineering", "open_date": "2024-01-01", "end_date": null, "currency_code": "USD", "salary_range": "[150000,200001)", "salary_min": 150000, "salary_max": 200000, "salary_details": "+ 0.5% equity, signing bonus negotiable", "billing_contact_name": "Sarah Chen", "billing_contact_email": "sarah.chen@startupxyz.com", "fee": 25000, "description": "We are looking for a Senior Software Engineer to join our platform team...", "team_members": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "email": "jane@company.com", "first_name": "Jane", "last_name": "Smith", "role_id": "345e6789-e01b-23c4-d567-890123456789", "role_name": "Team Lead" }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "email": "bob@company.com", "first_name": "Bob", "last_name": "Johnson", "role_id": "456e7890-f12b-34d5-e678-901234567890", "role_name": "Executive Sponsor" } ], "client_contacts": [ { "id": "c1d2e3f4-a5b6-7890-cdef-123456789012", "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Maria Gonzalez" } ], "share_links": [ { "id": "client-pipeline-abc123", "url": "https://stardex.com/share/startupxyz/client-pipeline-abc123", "title": "Client pipeline", "created_at": "2024-01-12T14:30:00Z", "requires_email_verification": true, "keep_active_when_job_closed": false } ], "linked_deals": [ { "deal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deal_job_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "StartupXYZ — Senior SWE retained search", "amount": 35000, "currency_code": "USD", "deal_status_id": "7201a0b8-e63c-4d8f-899d-78cdd62b5c38", "deal_status_name": "Qualified", "deal_status_color": "#10B981" } ], "fees": { "retainer": { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_type": "percentage", "fee_base": "first_year_salary", "fee_percentage": 25, "projected_fee": 50000, "estimated_compensation": 200000, "installment_count": 3, "final_payment_type": "on_placement", "currency_code": "USD" }, "fee_events": [ { "id": "f6a7b8c9-d0e1-2345-f012-456789012345", "type": "retainer", "label": "Engagement fee", "amount": 16666.67, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": 1, "start_date": "2024-01-05", "expected_date": "2024-01-10", "actual_payment_date": "2024-01-11", "candidate_id": null, "offer_id": null, "retainer_id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_status_id": "a7b8c9d0-e1f2-3456-0123-567890123456", "fee_status_name": "Paid", "fee_status_color": "#10B981", "fee_status_type": "paid", "linked_retainer_pack_id": null, "claimed_pack_retainer_id": null, "pack_retainer_amount": null }, { "id": "b8c9d0e1-f2a3-4567-1234-678901234567", "type": "placement", "label": "Placement — Jane Smith", "amount": 21333.33, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": null, "start_date": null, "expected_date": "2024-03-15", "actual_payment_date": null, "candidate_id": "234e5678-e90a-12b3-c456-789012345678", "offer_id": "c9d0e1f2-a3b4-5678-2345-789012345678", "retainer_id": null, "fee_status_id": "d0e1f2a3-b4c5-6789-3456-890123456789", "fee_status_name": "Invoiced", "fee_status_color": "#3B82F6", "fee_status_type": "invoiced", "linked_retainer_pack_id": "2b3c4d5e-6f70-4812-9a3b-c4d5e6f70812", "claimed_pack_retainer_id": "3c4d5e6f-7081-4923-ab4c-d5e6f7081923", "pack_retainer_amount": 12000 } ], "total_placement_fee": 50000 }, "job_status_changes": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "job_status_id": "111e2222-e33f-44a5-b666-777888999000", "job_status_name": "Not Started", "job_status_type": "not_started", "entered_at": "2024-01-01T12:00:00Z", "exited_at": "2024-01-10T09:00:00Z", "created_at": "2024-01-01T12:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": null }, { "id": "a2b3c4d5-e6f7-8901-bcde-f12345678901", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_name": "Active", "job_status_type": "in_progress", "entered_at": "2024-01-10T09:00:00Z", "exited_at": null, "created_at": "2024-01-10T09:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": "Kickoff complete" } ], "custom_fields": [ { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "attribute_name": "Priority", "data_type": "single-select", "value": null, "tag": { "id": "d4e5f6a7-b8c9-0123-defg-234567890123", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "attribute_name": "Sponsor", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ], "pipeline_stages": [ { "id": "345e6789-e01b-23c4-d567-890123456789", "job_pipeline_stage_id": "a12e3456-b78c-49d0-e123-456789012345", "name": "Application Review", "stage_order": 1000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false }, { "id": "456e7890-f12b-34d5-e678-901234567890", "job_pipeline_stage_id": "b23e4567-c89d-40e1-f234-567890123456", "name": "Phone Screen", "stage_order": 2000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "567e8901-e23c-45d6-e789-012345678901", "job_pipeline_stage_id": "c34e5678-d90e-41f2-a345-678901234567", "name": "Technical Interview", "stage_order": 2500, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "901e2345-b67c-89d0-e123-456789012345", "job_pipeline_stage_id": "d45e6789-e01f-42a3-b456-789012345678", "name": "Take Home Assessment", "stage_order": 2750, "is_archived": true, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "678e9012-f34d-56e7-f890-123456789012", "job_pipeline_stage_id": "e56e7890-f12a-43b4-c567-890123456789", "name": "Offer", "stage_order": 3000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": true, "is_placement_stage": false }, { "id": "789e0123-a45b-67c8-d901-234567890123", "job_pipeline_stage_id": "f67e8901-a23b-44c5-d678-901234567890", "name": "Rejected", "stage_order": 9000, "is_archived": false, "is_rejection_stage": true, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false } ] } ], "meta": { "total": 25, "offset": 0, "limit": 200 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}": { "get": { "operationId": "getJobById", "summary": "Get job by ID", "description": "Retrieve detailed information about a specific job including pipeline stages, team members with roles, candidate count, custom field values, linked client contacts, referral partners, active client-pipeline share links, linked CRM deals, fee & placement data (retainer structure, billing events and total placement fee from the \"Fees and Placements\" section), and the pack retainer split. Pass `include=job_status_changes` to embed the recorded status history, oldest first. Share links expired by a closed job (unless keep_active_when_job_closed is set) are omitted. With an API key, `linked_deals` needs the `deals:read` scope, `fees` needs `compensation:read`, and `referral_partners` and `pack_retainer_split` need `fees:read`. Sections your key cannot read are left out of the response.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job ID" } }, { "schema": { "type": "string", "description": "Comma-separated extra sections. Value: job_status_changes. Embeds the recorded status history on the job, oldest first. Omit to leave status history off the response. Pipeline stages, custom fields, client contacts, share links, linked deals, and fees are always returned on GET /v1/jobs/{id} and on the create response." }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Job fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobByIdResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Senior Software Engineer", "created_at": "2024-01-10T09:00:00Z", "is_archived": false, "client_company_name": "StartupXYZ", "client_company_id": "456e7890-e12b-34d5-a678-901234567890", "client_company_domain": "startupxyz.com", "client_company_linkedin_url": "https://www.linkedin.com/company/startupxyz", "job_status_name": "Active", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_type": "in_progress", "candidate_count": 12, "location": "San Francisco, CA", "primary_url": "https://startupxyz.com/careers/senior-swe", "job_function": "Engineering", "open_date": "2024-01-01", "end_date": null, "currency_code": "USD", "salary_range": "[150000,200001)", "salary_min": 150000, "salary_max": 200000, "salary_details": "+ 0.5% equity, signing bonus negotiable", "billing_contact_name": "Sarah Chen", "billing_contact_email": "sarah.chen@startupxyz.com", "fee": 25000, "description": "We are looking for a Senior Software Engineer to join our platform team...", "team_members": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "email": "jane@company.com", "first_name": "Jane", "last_name": "Smith", "role_id": "345e6789-e01b-23c4-d567-890123456789", "role_name": "Team Lead" }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "email": "bob@company.com", "first_name": "Bob", "last_name": "Johnson", "role_id": "456e7890-f12b-34d5-e678-901234567890", "role_name": "Executive Sponsor" } ], "client_contacts": [ { "id": "c1d2e3f4-a5b6-7890-cdef-123456789012", "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Maria Gonzalez" } ], "share_links": [ { "id": "client-pipeline-abc123", "url": "https://stardex.com/share/startupxyz/client-pipeline-abc123", "title": "Client pipeline", "created_at": "2024-01-12T14:30:00Z", "requires_email_verification": true, "keep_active_when_job_closed": false } ], "linked_deals": [ { "deal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deal_job_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "StartupXYZ — Senior SWE retained search", "amount": 35000, "currency_code": "USD", "deal_status_id": "7201a0b8-e63c-4d8f-899d-78cdd62b5c38", "deal_status_name": "Qualified", "deal_status_color": "#10B981" } ], "fees": { "retainer": { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_type": "percentage", "fee_base": "first_year_salary", "fee_percentage": 25, "projected_fee": 50000, "estimated_compensation": 200000, "installment_count": 3, "final_payment_type": "on_placement", "currency_code": "USD" }, "fee_events": [ { "id": "f6a7b8c9-d0e1-2345-f012-456789012345", "type": "retainer", "label": "Engagement fee", "amount": 16666.67, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": 1, "start_date": "2024-01-05", "expected_date": "2024-01-10", "actual_payment_date": "2024-01-11", "candidate_id": null, "offer_id": null, "retainer_id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "fee_status_id": "a7b8c9d0-e1f2-3456-0123-567890123456", "fee_status_name": "Paid", "fee_status_color": "#10B981", "fee_status_type": "paid", "linked_retainer_pack_id": null, "claimed_pack_retainer_id": null, "pack_retainer_amount": null }, { "id": "b8c9d0e1-f2a3-4567-1234-678901234567", "type": "placement", "label": "Placement — Jane Smith", "amount": 21333.33, "total_fee": 50000, "currency_code": "USD", "fee_type": "percentage", "fee_percentage": 25, "compensation": 200000, "firm_commission_percent": 100, "is_placeholder": false, "sequence": null, "start_date": null, "expected_date": "2024-03-15", "actual_payment_date": null, "candidate_id": "234e5678-e90a-12b3-c456-789012345678", "offer_id": "c9d0e1f2-a3b4-5678-2345-789012345678", "retainer_id": null, "fee_status_id": "d0e1f2a3-b4c5-6789-3456-890123456789", "fee_status_name": "Invoiced", "fee_status_color": "#3B82F6", "fee_status_type": "invoiced", "linked_retainer_pack_id": "2b3c4d5e-6f70-4812-9a3b-c4d5e6f70812", "claimed_pack_retainer_id": "3c4d5e6f-7081-4923-ab4c-d5e6f7081923", "pack_retainer_amount": 12000 } ], "total_placement_fee": 50000 }, "job_status_changes": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "job_status_id": "111e2222-e33f-44a5-b666-777888999000", "job_status_name": "Not Started", "job_status_type": "not_started", "entered_at": "2024-01-01T12:00:00Z", "exited_at": "2024-01-10T09:00:00Z", "created_at": "2024-01-01T12:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": null }, { "id": "a2b3c4d5-e6f7-8901-bcde-f12345678901", "job_status_id": "789e0123-e45f-67a8-b901-234567890123", "job_status_name": "Active", "job_status_type": "in_progress", "entered_at": "2024-01-10T09:00:00Z", "exited_at": null, "created_at": "2024-01-10T09:00:00Z", "created_by": "234e5678-e90a-12b3-c456-789012345678", "reason_text": "Kickoff complete" } ], "custom_fields": [ { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "attribute_name": "Priority", "data_type": "single-select", "value": null, "tag": { "id": "d4e5f6a7-b8c9-0123-defg-234567890123", "name": "High" }, "team_member": null, "company": null }, { "attribute_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "attribute_name": "Sponsor", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Acme Corp" } } ], "referral_partners": [ { "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Priya Natarajan", "title": "Managing Partner", "image_url": "https://example.com/priya-natarajan.png", "company_id": "678e9012-a34b-56c7-d890-123456789abc", "company_name": "Northwind Ventures", "default_split_percentage": 10, "default_mode": "off_the_top", "created_at": "2024-01-12T15:00:00Z" }, { "client_contact_id": "f4a5b6c7-d8e9-0123-fabc-456789012345", "person_id": "a5b6c7d8-e9f0-1234-abcd-567890123456", "name": "Tom Becker", "title": "Board Advisor", "image_url": null, "company_id": "456e7890-e12b-34d5-a678-901234567890", "company_name": "StartupXYZ", "default_split_percentage": null, "default_mode": "team_pool", "created_at": "2024-01-20T09:30:00Z" } ], "pack_retainer_split": [ { "team_member_id": "456e7890-a12b-34c5-d678-901234567890", "team_member_name": "Theo Martin", "role": "Sales", "split_percentage": 30 }, { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "role": null, "split_percentage": 35 }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "team_member_name": "Bob Johnson", "role": null, "split_percentage": 35 } ], "pipeline_stages": [ { "id": "345e6789-e01b-23c4-d567-890123456789", "job_pipeline_stage_id": "a12e3456-b78c-49d0-e123-456789012345", "name": "Application Review", "stage_order": 1000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false }, { "id": "456e7890-f12b-34d5-e678-901234567890", "job_pipeline_stage_id": "b23e4567-c89d-40e1-f234-567890123456", "name": "Phone Screen", "stage_order": 2000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "567e8901-e23c-45d6-e789-012345678901", "job_pipeline_stage_id": "c34e5678-d90e-41f2-a345-678901234567", "name": "Technical Interview", "stage_order": 2500, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "901e2345-b67c-89d0-e123-456789012345", "job_pipeline_stage_id": "d45e6789-e01f-42a3-b456-789012345678", "name": "Take Home Assessment", "stage_order": 2750, "is_archived": true, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "678e9012-f34d-56e7-f890-123456789012", "job_pipeline_stage_id": "e56e7890-f12a-43b4-c567-890123456789", "name": "Offer", "stage_order": 3000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": true, "is_placement_stage": false }, { "id": "789e0123-a45b-67c8-d901-234567890123", "job_pipeline_stage_id": "f67e8901-a23b-44c5-d678-901234567890", "name": "Rejected", "stage_order": 9000, "is_archived": false, "is_rejection_stage": true, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateJob", "summary": "Update job", "description": "Update fields on an existing job (title, job_description, status, location, salary range, salary details, billing contact name/email, fee, dates, archive state, linked deals, linked client contacts, custom fields). Use GET /v1/jobs/statuses for valid status IDs, GET /v1/custom-fields/jobs for custom field attribute IDs, and POST /v1/deals/search to resolve deal_ids for linking. Passing deal_ids fully replaces all existing deal_jobs links for the job; passing client_contact_ids fully replaces the client contacts on the job. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobRequest" } } } }, "responses": { "200": { "description": "Job updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobResponse" }, "example": { "success": true, "data": { "message": "Job updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/candidates": { "get": { "operationId": "listJobCandidates", "summary": "List job candidates", "description": "Retrieve a paginated list of ALL candidates in a specific job — no filtering.\n\n**When to use**: Only when you need every candidate regardless of stage, tags, or other criteria.\n\n**For filtered queries** (by pipeline stage, custom attributes/tags, name, location, etc.), use `POST /v1/persons/search` with `job_id` and `include: [\"candidates\"]` instead — it supports all person search filters and can return candidate-level fields in a single call.\n\n**Inbound applications** (Applicants tab) are a separate resource — use `GET /v1/jobs/{id}/applicants`.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job ID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Candidates fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCandidatesResponse" }, "example": { "success": true, "data": [ { "id": "234e5678-e90a-12b3-c456-789012345678", "person_id": "345e6789-e01b-23c4-d567-890123456789", "name": "Jane Smith", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "created_at": "2024-01-12T14:30:00Z", "sourced_by": "678e9012-e34d-56f7-a890-123456789012", "owner_id": "678e9012-e34d-56f7-a890-123456789012" } ], "meta": { "total": 12, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/applicants": { "get": { "operationId": "listJobApplicants", "summary": "List job applicants", "description": "Retrieve a paginated list of inbound applications submitted through the public job posting form (the Applicants tab).\n\nThis is **not** the job pipeline. Pipeline candidates — people already added to a stage — are returned by `GET /v1/jobs/{id}/candidates`.\n\n**Status values**: `new` (unprocessed), `selected` (added to the job pipeline; `person_id` is then set), `not_a_fit` (rejected from the Applicants tab).\n\nFile fields and `resume_url` / `cover_letter_url` are short-lived signed download URLs. Re-fetch this endpoint when a URL expires (about 15 minutes).\n\nJobs with no public posting return an empty list. Unknown job IDs return 404.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated applicant statuses to include. Values: new, selected, not_a_fit. Omit to return all statuses." }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Case-insensitive search across applicant name and email." }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Include applicants submitted on or after this ISO 8601 datetime (e.g. \"2024-01-01T00:00:00Z\")." }, "required": false, "name": "created_at_gte", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Include applicants submitted on or before this ISO 8601 datetime (e.g. \"2024-12-31T23:59:59Z\")." }, "required": false, "name": "created_at_lte", "in": "query" } ], "responses": { "200": { "description": "Applicants fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicantsResponse" }, "example": { "success": true, "data": [ { "id": "890e1234-b56c-78d9-e012-345678901234", "job_id": "123e4567-e89b-12d3-a456-426614174000", "job_posting_id": "901e2345-c67d-89e0-f123-456789012345", "person_id": null, "name": "Alex Rivera", "email": "alex.rivera@example.com", "status": "new", "linkedin_profile_url": "https://www.linkedin.com/in/alexrivera", "portfolio_url": "https://alexrivera.dev", "additional_information": "Available to start in two weeks.", "resume_url": "https://project.supabase.co/storage/v1/object/sign/job-application-documents/example-resume", "cover_letter_url": "https://project.supabase.co/storage/v1/object/sign/job-application-documents/example-cover-letter", "not_a_fit_note": null, "fields_response": { "fields": [ { "field_id": "full_name", "type": "text", "value": "Alex Rivera" }, { "field_id": "email", "type": "email", "value": "alex.rivera@example.com" }, { "field_id": "phone", "type": "phone", "value": "+1-555-0100" }, { "field_id": "linkedin_profile_url", "type": "url", "value": "https://www.linkedin.com/in/alexrivera" }, { "field_id": "cover_letter", "type": "textarea", "value": "I am excited to apply for this role." }, { "field_id": "years_experience", "type": "number", "value": 8 }, { "field_id": "start_date", "type": "date", "value": "2024-03-01" }, { "field_id": "work_authorization", "type": "select", "value": "US Citizen" }, { "field_id": "skills", "type": "multi_select", "value": [ "TypeScript", "React" ] }, { "field_id": "resume_file_path", "type": "file", "value": { "name": "Alex_Rivera_Resume.pdf", "size": 245760, "type": "application/pdf", "url": "https://project.supabase.co/storage/v1/object/sign/job-application-documents/example-resume" } } ] }, "created_at": "2024-02-01T15:45:00Z", "updated_at": "2024-02-01T15:45:00Z" } ], "meta": { "total": 8, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/document-types": { "get": { "operationId": "listJobDocumentTypes", "summary": "List job document types", "description": "Returns every active job document type for the organization, ordered by name. No pagination — the full list is always returned.\n\nDocument types are configurable per organization, so the available keys differ between organizations. Call this to discover valid `document_types` values for `GET /v1/jobs/{id}/documents` and valid `type` values when uploading a document.", "tags": [ "Jobs" ], "responses": { "200": { "description": "Job document types fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDocumentTypesResponse" }, "example": { "success": true, "data": [ { "type": "job_description", "name": "Job Description" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/documents": { "get": { "operationId": "getJobDocuments", "summary": "Get job documents", "description": "Retrieve a paginated list of documents attached to a job, including job descriptions, contracts, offer letters, and legal documents. Stored files receive short-lived signed download URLs; re-fetch when a URL expires. Pass include_text=true to receive extracted plain-text content when it is available.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "default": false, "description": "When true, includes extracted plain-text content when available. Omit or pass false for metadata and links only." }, "required": false, "name": "include_text", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated document type keys to filter by. Seeded values: job_description, offer_letter, contract, legal_document, other." }, "required": false, "name": "document_types", "in": "query" } ], "responses": { "200": { "description": "Documents fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDocumentsResponse" }, "example": { "success": true, "data": [ { "created_at": "2026-08-06T13:00:00Z", "updated_at": "2026-08-06T13:00:00Z", "type": "job_description", "title": "Senior Software Engineer Job Description.pdf", "link": "https://project.supabase.co/storage/v1/object/sign/job-documents/example", "text_content": "Senior Software Engineer role focused on distributed systems.", "char_count": 61, "truncated": false } ], "meta": { "total": 1, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "uploadJobDocument", "summary": "Upload job document", "description": "Upload a document for a job. Supports two modes:\n\n**1. Direct file upload** (`Content-Type: multipart/form-data`):\nSend the file in a `file` field with `title` and `type` metadata fields. Allowed file types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB.\n\n**2. JSON body** (`Content-Type: application/json`):\nProvide a `file_url` — a publicly accessible HTTPS URL. The server downloads the file, validates it, and stores it.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/JobDocumentUploadMultipart" } }, "application/json": { "schema": { "$ref": "#/components/schemas/JobDocumentUploadRequest" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDocumentUploadResponse" }, "example": { "success": true, "data": { "id": "a1b2c3d4-e5f6-4a78-9b01-234567890123", "created_at": "2026-08-06T13:00:00Z", "updated_at": "2026-08-06T13:00:00Z", "type": "job_description", "title": "Senior Software Engineer Job Description.pdf", "link": "https://project.supabase.co/storage/v1/object/sign/job-documents/example" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/target-companies": { "post": { "operationId": "addJobTargetCompanies", "summary": "Add job target companies", "description": "Add companies to a job target company list in bulk. Resolve company IDs with POST /v1/companies/search first. Invalid company IDs fail individually and do not block other valid IDs in the same request.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTargetCompaniesMutationRequest" } } } }, "responses": { "200": { "description": "Job target companies added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTargetCompaniesAddResponse" }, "example": { "success": true, "data": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "added_ids": [ "456e7890-e12b-34d5-a678-901234567890" ], "already_present_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "failed": [ { "id": "678e9012-f34d-56e7-f890-123456789012", "reason": "not_found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "removeJobTargetCompanies", "summary": "Remove job target companies", "description": "Remove companies from a job target company list in bulk. Resolve company IDs with POST /v1/companies/search first. Invalid company IDs fail individually and do not block other valid IDs in the same request.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTargetCompaniesMutationRequest" } } } }, "responses": { "200": { "description": "Job target companies removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTargetCompaniesRemoveResponse" }, "example": { "success": true, "data": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "removed_ids": [ "456e7890-e12b-34d5-a678-901234567890" ], "not_found_ids": [ "567e8901-e23c-45d6-e789-012345678901" ], "failed": [ { "id": "678e9012-f34d-56e7-f890-123456789012", "reason": "not_found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/team-member-roles": { "get": { "operationId": "listJobTeamMemberRoles", "summary": "List job team member roles", "description": "Retrieve all job team member roles for the current team. Use the returned `id` values when filtering by `team_member_role_ids` in `POST /v1/jobs/search` or `POST /v1/persons/search`.\n\nRoles are returned in display order (`position` ascending). Every team has at least one owner role (e.g. \"Team Lead\") indicated by `is_owner_role: true`.", "tags": [ "Jobs" ], "responses": { "200": { "description": "Roles fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTeamMemberRolesResponse" }, "example": { "success": true, "data": [ { "id": "345e6789-e01b-23c4-d567-890123456789", "name": "Team Lead", "is_owner_role": true, "position": 1 } ], "meta": { "total": 1, "offset": 0, "limit": 1 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/pack-retainer-split": { "get": { "operationId": "getJobPackRetainerSplit", "summary": "Get job pack retainer split", "description": "Returns the job's pack retainer split: who gets credit for a retainer pack retainer when a placement on this job claims it, and their percentages. When a placement claims a retainer from the client company's retainer pack, this split is copied onto that retainer and stays with it. An empty `splits` list means claimed retainers keep the pack default split. Needs `fees:read` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "responses": { "200": { "description": "Pack retainer split fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPackRetainerSplitResponse" }, "example": { "success": true, "data": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "splits": [ { "team_member_id": "456e7890-a12b-34c5-d678-901234567890", "team_member_name": "Theo Martin", "role": "Sales", "split_percentage": 30 }, { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "role": null, "split_percentage": 35 }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "team_member_name": "Bob Johnson", "role": null, "split_percentage": 35 } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "put": { "operationId": "replaceJobPackRetainerSplit", "summary": "Set job pack retainer split", "description": "Replaces the job's pack retainer split with the list you send. Percentages must total 100; send an empty list to remove the split so claimed retainers use the pack default. Retainers already claimed by a placement keep the split they were given; only later claims use the new one. Returns `422 SPLITS_MUST_TOTAL_100`, `422 INVALID_SPLIT_PERCENTAGE`, `422 DUPLICATE_TEAM_MEMBER` or `422 TEAM_MEMBER_NOT_FOUND` when the split is invalid. Session and OAuth callers need the admin role or the \"Edit jobs\" permission. Needs `fees:write` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceJobPackRetainerSplitRequest" } } } }, "responses": { "200": { "description": "Pack retainer split saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPackRetainerSplitResponse" }, "example": { "success": true, "data": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "splits": [ { "team_member_id": "456e7890-a12b-34c5-d678-901234567890", "team_member_name": "Theo Martin", "role": "Sales", "split_percentage": 30 }, { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "role": null, "split_percentage": 35 }, { "team_member_id": "345e6789-f01b-23c4-d567-890123456789", "team_member_name": "Bob Johnson", "role": null, "split_percentage": 35 } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Session and OAuth callers need the admin role or the \"Edit jobs\" permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "The split is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/referral-partners": { "get": { "operationId": "listJobReferralPartners", "summary": "List job referral partners", "description": "Returns the client contacts who referred this job, oldest first, with their default split percentage and payment mode. Partners can be paid a share of placement fees on this job: `off_the_top` takes the percentage from the full fee, `team_pool` shares the team commission pool. No pagination: the full list is always returned. Needs `fees:read` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "responses": { "200": { "description": "Referral partners fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobReferralPartnersListResponse" }, "example": { "success": true, "data": [ { "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Priya Natarajan", "title": "Managing Partner", "image_url": "https://example.com/priya-natarajan.png", "company_id": "678e9012-a34b-56c7-d890-123456789abc", "company_name": "Northwind Ventures", "default_split_percentage": 10, "default_mode": "off_the_top", "created_at": "2024-01-12T15:00:00Z" }, { "client_contact_id": "f4a5b6c7-d8e9-0123-fabc-456789012345", "person_id": "a5b6c7d8-e9f0-1234-abcd-567890123456", "name": "Tom Becker", "title": "Board Advisor", "image_url": null, "company_id": "456e7890-e12b-34d5-a678-901234567890", "company_name": "StartupXYZ", "default_split_percentage": null, "default_mode": "team_pool", "created_at": "2024-01-20T09:30:00Z" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "addJobReferralPartner", "summary": "Add job referral partner", "description": "Adds a client contact as a referral partner on the job. Any live client contact in your workspace can be added, from any company; find IDs with `GET /v1/client-contacts?keywords=...`. Returns `409 REFERRAL_PARTNER_EXISTS` when the contact is already a partner on this job, `404` when the contact is deleted or not in your workspace, and `422 INVALID_SPLIT_PERCENTAGE` when `default_split_percentage` is not more than 0 and at most 100. Session and OAuth callers need the admin role or the \"Edit jobs\" permission. Needs `fees:write` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Job UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddJobReferralPartnerRequest" } } } }, "responses": { "201": { "description": "Referral partner added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobReferralPartnerResponse" }, "example": { "success": true, "data": { "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Priya Natarajan", "title": "Managing Partner", "image_url": "https://example.com/priya-natarajan.png", "company_id": "678e9012-a34b-56c7-d890-123456789abc", "company_name": "Northwind Ventures", "default_split_percentage": 10, "default_mode": "off_the_top", "created_at": "2024-01-12T15:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Session and OAuth callers need the admin role or the \"Edit jobs\" permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The contact is already a referral partner on this job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "default_split_percentage is out of range", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/{id}/referral-partners/{client_contact_id}": { "patch": { "operationId": "updateJobReferralPartner", "summary": "Update job referral partner", "description": "Changes a referral partner's default split percentage, default payment mode, or both. Placements already logged keep their own partner splits. Returns `422 INVALID_SPLIT_PERCENTAGE` when `default_split_percentage` is not more than 0 and at most 100. Session and OAuth callers need the admin role or the \"Edit jobs\" permission. Needs `fees:write` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Job UUID." }, "required": true, "description": "Job UUID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Client contact UUID of the referral partner." }, "required": true, "description": "Client contact UUID of the referral partner.", "name": "client_contact_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobReferralPartnerRequest" } } } }, "responses": { "200": { "description": "Referral partner updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobReferralPartnerResponse" }, "example": { "success": true, "data": { "client_contact_id": "d2e3f4a5-b6c7-8901-defa-234567890123", "person_id": "e3f4a5b6-c7d8-9012-efab-345678901234", "name": "Priya Natarajan", "title": "Managing Partner", "image_url": "https://example.com/priya-natarajan.png", "company_id": "678e9012-a34b-56c7-d890-123456789abc", "company_name": "Northwind Ventures", "default_split_percentage": 10, "default_mode": "off_the_top", "created_at": "2024-01-12T15:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Session and OAuth callers need the admin role or the \"Edit jobs\" permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "default_split_percentage is out of range", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "removeJobReferralPartner", "summary": "Remove job referral partner", "description": "Removes a client contact from the referral partners of this job. The contact itself is not deleted, and placements already logged keep their partner splits. Session and OAuth callers need the admin role or the \"Edit jobs\" permission. Needs `fees:delete` for API keys.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Job UUID." }, "required": true, "description": "Job UUID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Client contact UUID of the referral partner." }, "required": true, "description": "Client contact UUID of the referral partner.", "name": "client_contact_id", "in": "path" } ], "responses": { "200": { "description": "Referral partner removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Referral partner removed from the job." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Session and OAuth callers need the admin role or the \"Edit jobs\" permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/statuses": { "get": { "operationId": "listJobStatuses", "summary": "List job statuses", "description": "Retrieve all job statuses for the team, including each status's lifecycle category (`status_type`: not_started, in_progress, closed_won, or closed_lost). Use the returned `id` values when filtering by `job_status_ids_included` in POST /v1/jobs/search or assigning `job_status_id` in POST /v1/jobs or PATCH /v1/jobs/{id}.", "tags": [ "Jobs" ], "responses": { "200": { "description": "Statuses fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusesResponse" }, "example": { "success": true, "data": [ { "id": "7201a0b8-e63c-4d8f-899d-78cdd62b5c38", "name": "Not Started", "color": "#cccccc", "stage_order": 1, "is_default_status": true, "status_type": "not_started" } ], "meta": { "total": 1, "offset": 0, "limit": 1 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/jobs/pipeline-stages": { "get": { "operationId": "listPipelineStages", "summary": "List pipeline stages", "description": "Retrieve all candidate pipeline stages for the team, including Stardex stage categories (`is_rejection_stage`, `is_interviewing_stage`, `is_offer_stage`, `is_placement_stage`). Use the returned `id` values when filtering persons by pipeline stage or moving candidates with POST /v1/candidates/update-stage.\n\nThis is the team-level catalog, sorted by a team-wide `stage_order` that is not any job's pipeline order. A job's own stages and their order are on GET /v1/jobs/{id}. Deleted stages are left out unless `include_deleted=true`; jobs and candidates can still refer to them.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": [ "boolean", "null" ], "default": false, "description": "When true, also returns stages deleted from the team's stages, with is_archived: true. Jobs and candidates can still refer to them." }, "required": false, "name": "include_deleted", "in": "query" } ], "responses": { "200": { "description": "Pipeline stages fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineStagesResponse" }, "example": { "success": true, "data": [ { "id": "345e6789-e01b-23c4-d567-890123456789", "name": "Application Review", "stage_order": 1000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false }, { "id": "456e7890-f12b-34d5-e678-901234567890", "name": "Phone Screen", "stage_order": 2000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "567e8901-e23c-45d6-e789-012345678901", "name": "Technical Interview", "stage_order": 2500, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "901e2345-b67c-89d0-e123-456789012345", "name": "Take Home Assessment", "stage_order": 2750, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": true, "is_offer_stage": false, "is_placement_stage": false }, { "id": "678e9012-f34d-56e7-f890-123456789012", "name": "Offer", "stage_order": 3000, "is_archived": false, "is_rejection_stage": false, "is_interviewing_stage": false, "is_offer_stage": true, "is_placement_stage": false }, { "id": "789e0123-a45b-67c8-d901-234567890123", "name": "Rejected", "stage_order": 9000, "is_archived": false, "is_rejection_stage": true, "is_interviewing_stage": false, "is_offer_stage": false, "is_placement_stage": false } ], "meta": { "total": 6, "offset": 0, "limit": 6 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/lists/search": { "post": { "operationId": "searchLists", "summary": "Search lists", "description": "Search and filter saved lists with pagination and sorting.\n\n**Filters**: `keywords` (name search), `list_type`, `is_archived`, `owner_ids`, `is_public`.\n\n**Sorting**: `name`, `created_at`, `updated_at`, `item_count`.\n\nReturns list metadata with item counts, owners, and creator info.", "tags": [ "Lists" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListsSearchBody" } } } }, "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListsSearchResponse" }, "example": { "success": true, "data": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Engineering Candidates Q2", "list_type": "persons", "is_public": true, "is_archived": false, "linked_job_id": "fff66666-0000-1111-2222-333333336666", "linked_person_id": null, "linked_organization_company_id": null, "item_count": 42, "created_by": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "first_name": "Jane", "last_name": "Smith" }, "owners": [ { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-05-20T14:30:00Z" } ], "meta": { "total": 100, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/lists/{id}": { "get": { "operationId": "getListById", "summary": "Get list by ID", "description": "Retrieve a single list by UUID with its paginated items.\n\nItems are paginated via `items_offset` and `items_limit` query parameters. Each item includes the referenced person or company details depending on the list type.", "tags": [ "Lists" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "List UUID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Items to skip for pagination. Defaults to 0." }, "required": false, "name": "items_offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items to return (1–100). Defaults to 50." }, "required": false, "name": "items_limit", "in": "query" } ], "responses": { "200": { "description": "List fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListByIdResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Engineering Candidates Q2", "list_type": "persons", "is_public": true, "is_archived": false, "linked_job_id": "fff66666-0000-1111-2222-333333336666", "linked_person_id": null, "linked_organization_company_id": null, "item_count": 42, "created_by": { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "first_name": "Jane", "last_name": "Smith" }, "owners": [ { "id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-05-20T14:30:00Z", "items": [ { "id": "eee55555-ffff-0000-1111-222222225555", "person": { "id": "ccc33333-dddd-eeee-ffff-000000003333", "first_name": "John", "last_name": "Doe", "linkedin_url": "https://linkedin.com/in/johndoe" }, "company": null, "created_at": "2024-02-01T12:00:00Z" } ], "items_total": 42 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/lists": { "post": { "operationId": "createList", "summary": "Create list", "description": "Create a new saved list. Lists can hold either persons or companies, determined by `list_type`. Optionally link to a job, person, or company.", "tags": [ "Lists" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreateRequest" } } } }, "responses": { "201": { "description": "List created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreateResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "name": "Engineering Candidates Q2", "list_type": "persons", "is_public": true, "is_archived": false, "linked_job_id": "fff66666-0000-1111-2222-333333336666", "linked_person_id": null, "linked_organization_company_id": null, "created_at": "2024-01-15T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/lists/{id}/items": { "post": { "operationId": "addListItems", "summary": "Add list items", "description": "Add persons or companies to a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request. Soft-deleted memberships are restored instead of duplicated.\n\n**Person-list auto-tagging**: When people are added or restored to a person list with list-scoped AI fields, background AI auto-tagging starts after this request completes. The response does not wait for tagging, and a successful list mutation does not guarantee that background tagging finishes successfully.", "tags": [ "Lists" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "List UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItemsMutationRequest" } } } }, "responses": { "200": { "description": "List items added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItemsAddResponse" }, "example": { "success": true, "data": { "list_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "list_type": "persons", "added_ids": [ "ccc33333-dddd-eeee-ffff-000000003333" ], "reactivated_ids": [], "already_present_ids": [], "failed": [ { "id": "99999999-8888-7777-6666-555555555555", "reason": "not_found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "removeListItems", "summary": "Remove list items", "description": "Soft-remove persons or companies from a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request.", "tags": [ "Lists" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "List UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItemsMutationRequest" } } } }, "responses": { "200": { "description": "List items removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItemsRemoveResponse" }, "example": { "success": true, "data": { "list_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "list_type": "persons", "removed_ids": [ "ccc33333-dddd-eeee-ffff-000000003333" ], "not_found_ids": [], "failed": [ { "id": "99999999-8888-7777-6666-555555555555", "reason": "not_found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/meeting-recordings": { "get": { "operationId": "listMeetingRecordings", "summary": "List meeting recordings", "description": "Retrieve a paginated list of meeting recordings with optional filters.\n\n**Filters**: `processing_status`, `calendar_meeting_id`, `meeting_started_after`, `meeting_started_before` (ISO 8601 date range).\n\n**Sorting**: `sort_by` (meeting_started_at, created_at, recording_duration_seconds) with `sort_order` (asc/desc, default desc).\n\n**Pagination**: Use `offset` and `limit` query params (max 100 per page).", "tags": [ "Meeting Recordings" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Filter by processing status. Use `completed` to find recordings with transcripts ready." }, "required": false, "name": "processing_status", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Filter recordings belonging to a specific calendar meeting." }, "required": false, "name": "calendar_meeting_id", "in": "query" }, { "schema": { "type": "string", "description": "Return recordings where the meeting started at or after this timestamp (ISO 8601). Example: `2026-04-01T00:00:00Z`." }, "required": false, "name": "meeting_started_after", "in": "query" }, { "schema": { "type": "string", "description": "Return recordings where the meeting started at or before this timestamp (ISO 8601). Example: `2026-04-30T23:59:59Z`." }, "required": false, "name": "meeting_started_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "meeting_started_at", "created_at", "recording_duration_seconds" ], "default": "created_at", "description": "Column to sort results by. Defaults to `created_at`.\n- `meeting_started_at` — when the meeting occurred\n- `created_at` — when the recording was created in the system\n- `recording_duration_seconds` — recording length" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (newest first)." }, "required": false, "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "Meeting recordings fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingRecordingsListResponse" }, "example": { "success": true, "data": [ { "id": "5c6d7e8f-9012-3456-7890-abcdef012345", "calendar_meeting_id": "6d7e8f90-1234-5678-9012-abcdef012345", "calendar_meeting": { "id": "6d7e8f90-1234-5678-9012-abcdef012345", "meeting_title": "Weekly Engineering Sync", "meeting_url": "https://meet.google.com/abc-defg-hij", "start_time": "2026-04-07T10:00:00.000Z" }, "meeting_started_at": "2026-04-07T10:00:00.000Z", "meeting_ended_at": "2026-04-07T11:00:00.000Z", "recording_duration_seconds": 3600, "processing_status": "completed", "has_transcript": true, "created_at": "2026-04-07T11:05:00.000Z", "updated_at": "2026-04-07T11:10:00.000Z" } ], "meta": { "total": 15, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/meeting-recordings/{id}": { "get": { "operationId": "getMeetingRecordingById", "summary": "Get meeting recording by ID", "description": "Retrieve detailed information about a specific meeting recording including the associated calendar meeting details and full transcript text.\n\nThe `transcript_text` field is always included. It will be null if the recording has not finished processing or no transcript was generated.", "tags": [ "Meeting Recordings" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Meeting recording UUID" } } ], "responses": { "200": { "description": "Meeting recording fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingRecordingByIdResponse" }, "example": { "success": true, "data": { "id": "5c6d7e8f-9012-3456-7890-abcdef012345", "calendar_meeting_id": "6d7e8f90-1234-5678-9012-abcdef012345", "calendar_meeting": { "id": "6d7e8f90-1234-5678-9012-abcdef012345", "meeting_title": "Weekly Engineering Sync", "meeting_url": "https://meet.google.com/abc-defg-hij", "start_time": "2026-04-07T10:00:00.000Z" }, "meeting_started_at": "2026-04-07T10:00:00.000Z", "meeting_ended_at": "2026-04-07T11:00:00.000Z", "recording_duration_seconds": 3600, "processing_status": "completed", "transcript_text": "Speaker 1: Good morning everyone...\nSpeaker 2: Hi, thanks for joining...", "summary_text": "Summary\n- Discussed Q2 roadmap and deliverables.\n- Agreed on hiring 2 senior engineers by May.\nNext Steps\n- Pranav to draft the JD.", "created_at": "2026-04-07T11:05:00.000Z", "updated_at": "2026-04-07T11:10:00.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/person-activities/types": { "get": { "operationId": "listPersonActivityTypes", "summary": "List person activity types", "description": "Returns every activity type registered for the requesting team, including built-in types (e.g. `secondary_note`, `email`, `meeting_note`) and any custom types defined under Settings → Activity Types. No pagination — the full list is returned in a single response.\n\n**When to use**: Call this before creating an activity with a custom `activity_type`, or before filtering `GET /v1/persons/{id}/activities` by `activity_types` / `excluded_activity_types`, so you know which keys are valid for the team.", "tags": [ "Person Activities" ], "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] }, { "type": "boolean" } ] }, "required": false, "name": "include_archived", "in": "query" } ], "responses": { "200": { "description": "Person activity types fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonActivityTypesListResponse" }, "example": { "success": true, "data": [ { "type": "reference_check", "name": "Reference Check", "protected": false, "counts_as_engagement": true, "is_archived": false, "system_generated": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/person-activities": { "post": { "operationId": "createPersonActivity", "summary": "Create person activity", "description": "Create a new activity (note, meeting, email, etc.) and attach it to a person record. The person can be identified by `person_id`, `email`, `linkedin_url`, or `full_name` — at least one is required.\n\n**Job association**: Pass optional `job_id` to link the activity to a specific search. When `job_id` is provided, the identified person must already be a candidate on that job; otherwise the request returns a 400 error.\n\n**Event time**: Optional `occurred_at` records when the event actually happened (ISO 8601). This is distinct from `created_at`, a system-managed timestamp for when the activity record was written — `created_at` cannot be set by the caller. If `occurred_at` is omitted, it defaults to `created_at`.\n\n**Attribution**: session and OAuth callers are always recorded as themselves. Pass `team_member_id` only when authenticating with an API key.\n\n**Supported activity types**: `secondary_note` (general note), `meeting_note`, `meeting_transcript`, `email`, `interview_note`, `linkedin_message`, `text_message`, `candidate_summary`, `linkedin_message_response`, `call_note`.", "tags": [ "Person Activities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPersonActivityRequest" } } } }, "responses": { "201": { "description": "Activity created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPersonActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89g0-h123-456789012345", "person_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/person-activities/{id}": { "get": { "operationId": "getPersonActivityById", "summary": "Get person activity by ID", "description": "Retrieve a single physical person activity by its UUID. Returns content in both HTML and plain text formats, plus `created_at` (system-managed record-write time) and `occurred_at` (when the event happened). Synthetic timeline activities, including `pipeline_status` entries, are not stored in `person_activities` and cannot be fetched from this endpoint.\n\n**When to use**: Use when you need the full content of a specific activity. For a paginated timeline of all activities for a person, use `GET /v1/persons/{id}/activities` instead.", "tags": [ "Person Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Person activity ID" } } ], "responses": { "200": { "description": "Activity fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonActivityResponse" }, "example": { "success": true, "data": { "id": "901e2345-e67f-89g0-h123-456789012345", "person_id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "activity_content": "

Had a great conversation about the role requirements.

", "activity_raw_content": "Had a great conversation about the role requirements.", "created_at": "2024-01-15T10:30:00Z", "occurred_at": "2024-01-10T14:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updatePersonActivityById", "summary": "Update person activity by ID", "description": "Update an existing person activity. You can change the content, the activity type, the event time, or any combination.\n\n**Content**: Set `content_type` to `\"text\"` for plain text (auto-converted to HTML) or `\"html\"` for raw HTML input.\n\n**Activity type**: Pass `activity_type` to change the type. The new type must be registered for the team — discover valid types with `GET /v1/person-activities/types`.\n\n**Event time**: Optional `occurred_at` sets when the event actually happened (ISO 8601). This is distinct from `created_at`, which is system-managed and cannot be changed. At least one of `activity_content`, `activity_type`, or `occurred_at` must be provided.", "tags": [ "Person Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Person activity ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonActivityBody" } } } }, "responses": { "200": { "description": "Activity updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonActivityResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "activity_type": "meeting_note", "updated_at": "2024-03-15T12:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deletePersonActivityById", "summary": "Delete person activity by ID", "description": "Remove a person activity from the person timeline. Deleted activities cannot be retrieved or updated.", "tags": [ "Person Activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Person activity ID" } } ], "responses": { "200": { "description": "Activity deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Activity deleted successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Activity cannot be deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/reference-types": { "get": { "operationId": "listPersonReferenceTypes", "summary": "List person reference types", "description": "List the reference types configured for your workspace (for example Colleague, Manager, Friend). Use the `type` key as `reference_type` when creating or updating a reference.", "tags": [ "Persons" ], "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] }, { "type": "boolean" } ], "description": "When true, also return archived reference types. Archived types cannot be used for new references but may still appear on existing ones." }, "required": false, "name": "include_archived", "in": "query" } ], "responses": { "200": { "description": "Reference types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceTypesResponse" }, "example": { "success": true, "data": [ { "type": "colleague", "name": "Colleague", "is_archived": false }, { "type": "manager", "name": "Manager", "is_archived": false }, { "type": "previous_manager", "name": "Previous Manager", "is_archived": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/references": { "post": { "operationId": "createPersonReference", "summary": "Create person reference", "description": "Add a reference for the person in the path: the person who gave it (`related_person_id`), how they know each other (`reference_type`), an optional strength and a formatted note. Set `occurred_at` to record when the reference actually happened; it defaults to `created_at`, the same as for person activities.\n\nA reference reads from the person in the path to the related person: a `previous_manager` reference added on John with Jane as the related person shows in the app as \"John · Previous Manager · Jane\". The reference appears on both people, including in their activity timelines (`GET /v1/persons/{id}/activities`, activity type `person_reference`).", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceCreateRequest" } } } }, "responses": { "201": { "description": "Reference created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceResponse" }, "example": { "success": true, "data": { "id": "3f2c8a1e-5b7d-4c9e-8a1f-2d3e4f5a6b7c", "person_id": "123e4567-e89b-12d3-a456-426614174000", "related_person": { "id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "VP Engineering", "current_company_name": "Tech Corp" }, "reference_type": "previous_manager", "reference_type_name": "Previous Manager", "reference_strength": "high", "direction": "outgoing", "note": "Reference call on May 12.\nWould hire him again for any platform role.", "note_html": "

Reference call on May 12.

\n

Would hire him again for any platform role.

", "created_by": "890e1234-e56f-78a9-b012-345678901234", "occurred_at": "2026-05-11T15:00:00Z", "created_at": "2026-05-12T16:20:00Z", "updated_at": "2026-05-12T16:20:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/references/{reference_id}": { "patch": { "operationId": "updatePersonReference", "summary": "Update person reference", "description": "Update the type, strength, note or `occurred_at` of a reference. The person in the path can be either end of the reference. Only provided fields change; pass null to clear `reference_strength` or `note`. Find reference IDs with `GET /v1/persons/{id}?include=references`.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } }, { "in": "path", "name": "reference_id", "required": true, "schema": { "type": "string", "description": "Reference UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceUpdateRequest" } } } }, "responses": { "200": { "description": "Reference updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceResponse" }, "example": { "success": true, "data": { "id": "3f2c8a1e-5b7d-4c9e-8a1f-2d3e4f5a6b7c", "person_id": "123e4567-e89b-12d3-a456-426614174000", "related_person": { "id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "VP Engineering", "current_company_name": "Tech Corp" }, "reference_type": "previous_manager", "reference_type_name": "Previous Manager", "reference_strength": "high", "direction": "outgoing", "note": "Reference call on May 12.\nWould hire him again for any platform role.", "note_html": "

Reference call on May 12.

\n

Would hire him again for any platform role.

", "created_by": "890e1234-e56f-78a9-b012-345678901234", "occurred_at": "2026-05-11T15:00:00Z", "created_at": "2026-05-12T16:20:00Z", "updated_at": "2026-05-12T16:20:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deletePersonReference", "summary": "Delete person reference", "description": "Delete a reference. It is removed from both people. The person in the path can be either end of the reference. This cannot be undone.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } }, { "in": "path", "name": "reference_id", "required": true, "schema": { "type": "string", "description": "Reference UUID" } } ], "responses": { "200": { "description": "Reference deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonReferenceDeleteResponse" }, "example": { "success": true, "message": "Reference deleted successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons": { "get": { "operationId": "listPersons", "summary": "List persons (deprecated)", "deprecated": true, "description": "**Deprecated** — Use `POST /v1/persons/search` instead for full filtering, sorting, and include control.\n\nRetrieve a paginated list of ALL persons with optional sorting — no filtering.\n\n**Pagination**: Use `offset` and `limit` query params (max 100 per page).\n\n**Sorting**: Set `sort_by` to one of: `name`, `created_at`, `updated_at`, `current_job_title`, `company`, `location`, `date_of_last_engagement`, `person_owner`, `last_activity_type`, `contact_email`, or `custom_` for custom fields. Use `sort_order` (`asc` or `desc`, default `desc`).\n\n**Include control**: The `include` query param accepts a comma-separated list of section names. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `references`, `offers`, `team_connections`. `related_people` is a deprecated alias for `references` that returns the older shape. When omitted, defaults to `work_experience, education_experience, certifications`. Pass an empty string to return only base fields.\n\n**API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, `compensation` and `offers` require `compensation:read`, and `team_connections` requires `connections:read`.", "tags": [ "Persons" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Sort column. Values: name, created_at, updated_at, current_job_title, company, location, date_of_last_engagement, person_owner, last_activity_type, contact_email, or custom_ for custom fields. Defaults to created_at.", "example": "created_at" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to desc (newest first)." }, "required": false, "name": "sort_order", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated sections to embed in each person. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, references, offers, team_connections (related_people is a deprecated alias for references in the older shape). Default: work_experience, education_experience, certifications. Pass empty string for base fields only (id, name, emails, phones, etc.). For API-key callers, unavailable requested sections are omitted: activities requires notes:read, candidates requires candidates:read, compensation and offers require compensation:read, and team_connections requires connections:read.", "example": "work_experience,candidates,custom_fields" }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonsSearchResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "external_source_id": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:45:00.000Z", "image_url": "https://media.samplecdn.com/dms/image/example.jpg", "location": "San Francisco, CA", "latitude": 37.7749, "longitude": -122.4194, "date_of_last_engagement": "2024-06-18T09:00:00.000Z", "last_activity_type": "email", "do_not_contact": false, "do_not_contact_reason": null, "do_not_contact_expiration_date": null, "owner_id": null, "preferred_email": "john@techcorp.com", "preferred_phone": "+1-555-0123", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com", "is_preferred": true, "is_bounced": false }, { "contact_data_type": "personal", "value": "john@gmail.com", "is_preferred": false, "is_bounced": false } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123", "is_preferred": true } ], "work_experience": [ { "company_name": "Tech Corp", "company_linkedin_url": "https://www.linkedin.com/company/techcorp", "company_linkedin_id": 12345678, "company_id": "456e7890-e12b-34d5-a678-901234567890", "duration_in_months": 36, "positions": [ { "title": "Software Engineer", "start_date": "2022-01-01", "end_date": null, "duration_in_months": 36, "description": "Full-stack development", "location": "San Francisco, CA", "position_type": "Full-time" } ] } ], "education_experience": [ { "company_name": "Stanford University", "start_date": "2016-09-01", "end_date": "2020-06-01", "description": null, "degree": "B.S. Computer Science", "company_linkedin_url": "https://www.linkedin.com/school/stanford", "company_linkedin_id": 1234, "company_id": null } ], "certifications": [ { "name": "AWS Solutions Architect", "credential_id": "AWS-SA-001", "start_date": "2023-06-01", "end_date": "2026-06-01", "company_name": "Amazon Web Services", "company_linkedin_url": null, "company_linkedin_id": null, "company_id": null } ], "candidates": [ { "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "job_name": "Senior Software Engineer", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_client_company_name": "StartupXYZ", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "is_archived": false, "created_at": "2024-01-12T14:30:00Z", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "owner_id": null } ], "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attribute_name": "Seniority Level", "data_type": "single-select", "value": null, "tag": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Senior" }, "team_member": null, "company": null }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "attribute_name": "Years of Experience", "data_type": "decimal", "value": 8, "tag": null, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Tech Corp" } } ], "activities": [ { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } } ], "compensation": [ { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "actual", "currency_code": "USD", "current_compensation_base": 180000, "current_compensation_bonus": 20000, "bonus_percent": null, "equity_percent": null, "equity_amount": 50000, "compensation_year": 2024, "total_estimated_compensation": 250000, "note": "Current package at Tech Corp", "job_id": null, "job_name": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "related_people": [ { "relation_id": "rel-1111-2222-3333-444444444444", "person_id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "Engineering Manager", "linkedin_public_id": "janesmith", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "relation_type": "colleague", "relation_type_name": "Colleague", "relation_strength": "medium", "note": "Worked together on Platform team", "note_html": "

Worked together on Platform team

", "direction": "outgoing", "occurred_at": "2024-01-04T15:00:00Z", "created_at": "2024-01-05T10:00:00Z" } ], "offers": [ { "id": "offer-1111-2222-3333-444444444444", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_name": "Senior Software Engineer", "job_company_name": "StartupXYZ", "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "status": { "id": "status-1111", "name": "Extended", "color": "#22c55e", "status_type": "pending" }, "extended_date": "2024-02-01T00:00:00Z", "accepted_date": null, "candidate_start_date": "2024-03-01T00:00:00Z", "compensation_currency": "USD", "compensation_base": 200000, "compensation_bonus": 30000, "bonus_type": "fixed", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": null, "initial_equity_grant_amount": 100000, "relocation_bonus": 10000, "sign_on_bonus": 25000, "total_estimated_compensation": 315000, "note": "Competitive offer with strong equity component", "created_at": "2024-02-01T00:00:00Z", "updated_at": "2024-02-01T00:00:00Z" } ], "team_connections": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "is_former_member": false, "strength": "high", "linkedin_connected_on": "2021-08-18" } ] } ], "meta": { "total": 100, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "createPerson", "summary": "Create person", "description": "Create a new person record with contact details and optional job association. Returns the created person with IDs for further operations. Pass `custom_fields` to set custom field values in the same call, and `sourced_by` with `job_id` to record which team member sourced the candidate.\n\n**Warning:** `linkedin_url` is optional but **strongly recommended**. It is the only reliable deduplication key for this endpoint. When provided, an existing person with that LinkedIn profile is matched and updated (never duplicated).\n\n**Automatic merge:** when the new person has the same name as exactly one existing person, and also shares their email and phone number (or shares one of them, and their work histories, current company included, have a company in common or one of them has no work history), the new record is merged into the existing one. A new person whose `external_source_id` differs from the existing person's is never merged. The response then describes the existing person, including its `id`. Merges are listed under Settings → Audit Log → Merged Records. If none of these conditions hold, a new person is created, so prefer `PATCH /v1/persons/{id}` when you already have the person ID.", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCreateRequest" }, "example": { "name": "John Doe", "first_name": "John", "last_name": "Doe", "linkedin_url": "https://www.linkedin.com/in/johndoe", "current_job_title": "Software Engineer", "location": "San Francisco, CA", "company_name": "Tech Corp", "emails": [ "john.doe@example.com" ], "work_email": "john@techcorp.com", "work_phone": "+1-555-0100", "personal_email": "john.doe@gmail.com", "mobile_phone": "+1-555-0123", "phone_numbers": [ "+1-555-0199" ], "notes": "Strong backend experience, open to relocation.", "job_id": "345e6789-e01b-23c4-d567-890123456789", "external_source_id": "ext-candidate-12345", "enrich_record": true, "person_owner": "234e5678-e90a-12b3-c456-789012345678", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "value": "Senior" }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "value": 8 }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "add_company_ids": [ "456e7890-e12b-34d5-a678-901234567890" ] } ] } } } }, "responses": { "201": { "description": "Person created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCreateResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "current_job_title": "Software Engineer", "company_name": "Tech Corp", "location": "San Francisco, CA", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com" } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123" } ], "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "client_contact_id": null, "external_source_id": null } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The person asked to be deleted from, or not contacted by, your workspace, and their email or LinkedIn profile is on its do-not-re-add list. They are added again only if they apply to one of your jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "example": { "success": false, "error": { "code": "PERSON_DELETION_REQUESTED", "message": "This person asked to be removed from your workspace and can't be added again." } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/search": { "post": { "operationId": "searchPersons", "summary": "Advanced person search", "description": "The primary tool for finding and filtering persons across the entire database. All filters are optional and combinable. Use this instead of list-persons for any filtered query.\n\n**Direct search fields**: `email` (exact match), `name` (ranked lookup on name, title, company, and location; top matches, not exhaustive), `phone` (tiered matching: exact → normalized → last-7-digits), `linkedin_url` (exact profile match), `vector_search` (AI semantic search, min 5 chars).\n\n**Filter categories**: jobs & pipeline stages, job titles, departments, companies (current/past), activity types, owners & dates, activity content keywords, owners (person/candidate), source, lists, contact presence, engagement recency, date ranges (created_at, updated_at, added-to-job), locations, and custom attributes (select, numeric, date, team member, company).\n\n**Activity filters**: `activity_types_*`, `activity_owner_ids_*` and `activity_date_*` all apply to the same activity. For example, `activity_types_included: [\"\"]` with `activity_date_type: \"within_last\"`, `activity_date_value: 7`, `activity_date_unit: \"days\"` returns persons with an activity of that type in the last 7 days. With only `activity_types_excluded` set, the owner and date filters scope the exclusion instead (persons with no activity of that type in the window). Get type keys from `GET /v1/person-activities/types` and team member IDs from `GET /v1/team-members`.\n\n**Custom field / tag filtering**: To filter by person tags or select-type attributes (e.g. \"banking\" tag), use `select_attribute_filters` with `attribute_id` and `values` (tag UUIDs). To discover attribute IDs and tag option IDs, call `GET /v1/custom-fields/persons` first.\n\n**Sorting**: Set `sort_by` to one of: `name`, `created_at`, `updated_at`, `current_job_title`, `company`, `location`, `date_of_last_engagement`, `person_owner`, `last_activity_type`, `contact_email`, or `custom_`. Job-context sort columns (require `job_id` or exactly 1 job in `job_ids_included`): `pipeline_stage`, `stage_date`, `added_to_job_at`, `rating`, `rating_note`, `candidate_owner`. Use `sort_order` (`asc` or `desc`, default `desc`).\n\n**Include control**: The `include` body array controls which sections appear in each person record. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `references`, `offers`, `team_connections`. `related_people` is a deprecated alias for `references` that returns the older shape. When omitted, returns only base fields (id, name, emails, phones, preferred_email, preferred_phone, current_job_title, etc.). Pass an empty array `[]` to explicitly request base fields only.\n\n**API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, `compensation` and `offers` require `compensation:read`, and `team_connections` requires `connections:read`. `activity_content_keywords` searches note and document text, so API keys must hold both `notes:read` and `documents:read` or the request is rejected.\n\n**Job-scoped search**: Pass `job_id` to scope results to candidates in a specific job. This enables job-context sort columns and automatically filters to persons in that job. Combine with `include: [\"candidates\"]` to get candidate-level fields (pipeline stage, sourced_by, etc.).", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonsSearchBody" } } } }, "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonsSearchResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "external_source_id": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:45:00.000Z", "image_url": "https://media.samplecdn.com/dms/image/example.jpg", "location": "San Francisco, CA", "latitude": 37.7749, "longitude": -122.4194, "date_of_last_engagement": "2024-06-18T09:00:00.000Z", "last_activity_type": "email", "do_not_contact": false, "do_not_contact_reason": null, "do_not_contact_expiration_date": null, "owner_id": null, "preferred_email": "john@techcorp.com", "preferred_phone": "+1-555-0123", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com", "is_preferred": true, "is_bounced": false }, { "contact_data_type": "personal", "value": "john@gmail.com", "is_preferred": false, "is_bounced": false } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123", "is_preferred": true } ], "work_experience": [ { "company_name": "Tech Corp", "company_linkedin_url": "https://www.linkedin.com/company/techcorp", "company_linkedin_id": 12345678, "company_id": "456e7890-e12b-34d5-a678-901234567890", "duration_in_months": 36, "positions": [ { "title": "Software Engineer", "start_date": "2022-01-01", "end_date": null, "duration_in_months": 36, "description": "Full-stack development", "location": "San Francisco, CA", "position_type": "Full-time" } ] } ], "education_experience": [ { "company_name": "Stanford University", "start_date": "2016-09-01", "end_date": "2020-06-01", "description": null, "degree": "B.S. Computer Science", "company_linkedin_url": "https://www.linkedin.com/school/stanford", "company_linkedin_id": 1234, "company_id": null } ], "certifications": [ { "name": "AWS Solutions Architect", "credential_id": "AWS-SA-001", "start_date": "2023-06-01", "end_date": "2026-06-01", "company_name": "Amazon Web Services", "company_linkedin_url": null, "company_linkedin_id": null, "company_id": null } ], "candidates": [ { "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "job_name": "Senior Software Engineer", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_client_company_name": "StartupXYZ", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "is_archived": false, "created_at": "2024-01-12T14:30:00Z", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "owner_id": null } ], "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attribute_name": "Seniority Level", "data_type": "single-select", "value": null, "tag": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Senior" }, "team_member": null, "company": null }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "attribute_name": "Years of Experience", "data_type": "decimal", "value": 8, "tag": null, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Tech Corp" } } ], "activities": [ { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } } ], "compensation": [ { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "actual", "currency_code": "USD", "current_compensation_base": 180000, "current_compensation_bonus": 20000, "bonus_percent": null, "equity_percent": null, "equity_amount": 50000, "compensation_year": 2024, "total_estimated_compensation": 250000, "note": "Current package at Tech Corp", "job_id": null, "job_name": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "related_people": [ { "relation_id": "rel-1111-2222-3333-444444444444", "person_id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "Engineering Manager", "linkedin_public_id": "janesmith", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "relation_type": "colleague", "relation_type_name": "Colleague", "relation_strength": "medium", "note": "Worked together on Platform team", "note_html": "

Worked together on Platform team

", "direction": "outgoing", "occurred_at": "2024-01-04T15:00:00Z", "created_at": "2024-01-05T10:00:00Z" } ], "offers": [ { "id": "offer-1111-2222-3333-444444444444", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_name": "Senior Software Engineer", "job_company_name": "StartupXYZ", "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "status": { "id": "status-1111", "name": "Extended", "color": "#22c55e", "status_type": "pending" }, "extended_date": "2024-02-01T00:00:00Z", "accepted_date": null, "candidate_start_date": "2024-03-01T00:00:00Z", "compensation_currency": "USD", "compensation_base": 200000, "compensation_bonus": 30000, "bonus_type": "fixed", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": null, "initial_equity_grant_amount": 100000, "relocation_bonus": 10000, "sign_on_bonus": 25000, "total_estimated_compensation": 315000, "note": "Competitive offer with strong equity component", "created_at": "2024-02-01T00:00:00Z", "updated_at": "2024-02-01T00:00:00Z" } ], "team_connections": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "is_former_member": false, "strength": "high", "linkedin_connected_on": "2021-08-18" } ] } ], "meta": { "total": 100, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}": { "get": { "operationId": "getPersonById", "summary": "Get person by ID", "description": "Retrieve detailed information about a specific person by their UUID.\n\n**Include control**: The `include` query param accepts a comma-separated list of section names to control the response shape. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `references`, `offers`, `team_connections`. `related_people` is a deprecated alias for `references` that returns the older shape. When omitted, defaults to: `work_experience`, `education_experience`, `certifications`, `custom_fields`. Pass an empty string to return only base fields (id, name, emails, phones, preferred_email, preferred_phone, current_job_title, etc.).\n\nNote: The `activities` section returns up to 50 most recent activities. For full pagination, use `GET /v1/persons/{id}/activities`.\n\n**API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, `compensation` and `offers` require `compensation:read`, and `team_connections` requires `connections:read`.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person ID" } }, { "schema": { "type": "string", "description": "Comma-separated sections to embed. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, references, offers, team_connections (related_people is a deprecated alias for references in the older shape). Default: work_experience, education_experience, certifications, custom_fields. Pass empty string for base fields only. \"activities\" returns up to 50 most recent — use GET /v1/persons/{id}/activities for full pagination. For API-key callers, unavailable requested sections are omitted: activities requires notes:read, candidates requires candidates:read, compensation and offers require compensation:read, and team_connections requires connections:read.", "example": "candidates,custom_fields,activities" }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Person found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonByIdResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "external_source_id": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:45:00.000Z", "image_url": "https://media.samplecdn.com/dms/image/example.jpg", "location": "San Francisco, CA", "latitude": 37.7749, "longitude": -122.4194, "date_of_last_engagement": "2024-06-18T09:00:00.000Z", "last_activity_type": "email", "do_not_contact": false, "do_not_contact_reason": null, "do_not_contact_expiration_date": null, "owner_id": null, "preferred_email": "john@techcorp.com", "preferred_phone": "+1-555-0123", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com", "is_preferred": true, "is_bounced": false }, { "contact_data_type": "personal", "value": "john@gmail.com", "is_preferred": false, "is_bounced": false } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123", "is_preferred": true } ], "work_experience": [ { "company_name": "Tech Corp", "company_linkedin_url": "https://www.linkedin.com/company/techcorp", "company_linkedin_id": 12345678, "company_id": "456e7890-e12b-34d5-a678-901234567890", "duration_in_months": 36, "positions": [ { "title": "Software Engineer", "start_date": "2022-01-01", "end_date": null, "duration_in_months": 36, "description": "Full-stack development", "location": "San Francisco, CA", "position_type": "Full-time" } ] } ], "education_experience": [ { "company_name": "Stanford University", "start_date": "2016-09-01", "end_date": "2020-06-01", "description": null, "degree": "B.S. Computer Science", "company_linkedin_url": "https://www.linkedin.com/school/stanford", "company_linkedin_id": 1234, "company_id": null } ], "certifications": [ { "name": "AWS Solutions Architect", "credential_id": "AWS-SA-001", "start_date": "2023-06-01", "end_date": "2026-06-01", "company_name": "Amazon Web Services", "company_linkedin_url": null, "company_linkedin_id": null, "company_id": null } ], "candidates": [ { "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "job_name": "Senior Software Engineer", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_client_company_name": "StartupXYZ", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "is_archived": false, "created_at": "2024-01-12T14:30:00Z", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "owner_id": null } ], "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attribute_name": "Seniority Level", "data_type": "single-select", "value": null, "tag": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Senior" }, "team_member": null, "company": null }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "attribute_name": "Years of Experience", "data_type": "decimal", "value": 8, "tag": null, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Tech Corp" } } ], "activities": [ { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } } ], "compensation": [ { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "actual", "currency_code": "USD", "current_compensation_base": 180000, "current_compensation_bonus": 20000, "bonus_percent": null, "equity_percent": null, "equity_amount": 50000, "compensation_year": 2024, "total_estimated_compensation": 250000, "note": "Current package at Tech Corp", "job_id": null, "job_name": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "related_people": [ { "relation_id": "rel-1111-2222-3333-444444444444", "person_id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "Engineering Manager", "linkedin_public_id": "janesmith", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "relation_type": "colleague", "relation_type_name": "Colleague", "relation_strength": "medium", "note": "Worked together on Platform team", "note_html": "

Worked together on Platform team

", "direction": "outgoing", "occurred_at": "2024-01-04T15:00:00Z", "created_at": "2024-01-05T10:00:00Z" } ], "offers": [ { "id": "offer-1111-2222-3333-444444444444", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_name": "Senior Software Engineer", "job_company_name": "StartupXYZ", "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "status": { "id": "status-1111", "name": "Extended", "color": "#22c55e", "status_type": "pending" }, "extended_date": "2024-02-01T00:00:00Z", "accepted_date": null, "candidate_start_date": "2024-03-01T00:00:00Z", "compensation_currency": "USD", "compensation_base": 200000, "compensation_bonus": 30000, "bonus_type": "fixed", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": null, "initial_equity_grant_amount": 100000, "relocation_bonus": 10000, "sign_on_bonus": 25000, "total_estimated_compensation": 315000, "note": "Competitive offer with strong equity component", "created_at": "2024-02-01T00:00:00Z", "updated_at": "2024-02-01T00:00:00Z" } ], "team_connections": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "is_former_member": false, "strength": "high", "linkedin_connected_on": "2021-08-18" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updatePerson", "summary": "Update person", "description": "Update an existing person's information including contact details, job title, company, do-not-contact status, and custom field values. Only provided fields are updated; omitted fields remain unchanged.\n\n**Do-not-contact**: Pass `do_not_contact: true` to flag the person or `false` to clear it. Optionally include a `do_not_contact_reason` (free text) and `do_not_contact_expiration_date` (ISO 8601 timestamp). Pass `null` for an indefinite do-not-contact. When the expiration field is omitted on a new flag, the do-not-contact is indefinite; when omitted on an existing flag, the current expiration is preserved.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonRequest" } } } }, "responses": { "200": { "description": "Person updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonResponse" }, "example": { "success": true, "data": { "message": "Person updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The person asked to be deleted from, or not contacted by, your workspace, and their email or LinkedIn profile is on its do-not-re-add list. Returned when the update adds one of those identifiers to this person.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "example": { "success": false, "error": { "code": "PERSON_DELETION_REQUESTED", "message": "This person asked to be removed from your workspace and can't be added again." } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/compensations": { "post": { "operationId": "createPersonCompensation", "summary": "Create person compensation", "description": "Create a compensation history record for a person. Use this for current, desired, or minimum compensation details. If `job_id` is provided, the person must already be a candidate on that job.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCompensationCreateRequest" } } } }, "responses": { "201": { "description": "Compensation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCompensationResponse" }, "example": { "success": true, "data": { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "desired", "currency_code": "USD", "current_compensation_base": 200000, "current_compensation_bonus": null, "bonus_percent": null, "equity_percent": null, "equity_amount": null, "compensation_year": 2026, "total_estimated_compensation": 200000, "note": "Target base salary discussed with the candidate.", "job_id": null, "job_name": null, "created_at": "2026-05-27T21:30:00Z", "updated_at": "2026-05-27T21:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/compensations/{compensation_id}": { "patch": { "operationId": "updatePersonCompensation", "summary": "Update person compensation", "description": "Update one compensation history record for a person. Only provided fields are changed; pass null for nullable fields to clear them.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } }, { "in": "path", "name": "compensation_id", "required": true, "schema": { "type": "string", "description": "Compensation UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCompensationUpdateRequest" } } } }, "responses": { "200": { "description": "Compensation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCompensationResponse" }, "example": { "success": true, "data": { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "desired", "currency_code": "USD", "current_compensation_base": 200000, "current_compensation_bonus": null, "bonus_percent": null, "equity_percent": null, "equity_amount": null, "compensation_year": 2026, "total_estimated_compensation": 200000, "note": "Target base salary discussed with the candidate.", "job_id": null, "job_name": null, "created_at": "2026-05-27T21:30:00Z", "updated_at": "2026-05-27T21:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deletePersonCompensation", "summary": "Delete person compensation", "description": "Delete one compensation history record from a person.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } }, { "in": "path", "name": "compensation_id", "required": true, "schema": { "type": "string", "description": "Compensation UUID" } } ], "responses": { "200": { "description": "Compensation deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonCompensationDeleteResponse" }, "example": { "success": true, "message": "Compensation deleted successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/activities": { "get": { "operationId": "getPersonActivities", "summary": "Get unified person activities", "description": "Retrieve a unified, paginated timeline of all activities for a person. Aggregates notes, emails, tasks, calendar events, sequence enrollments, pipeline stage changes, and assessments. Each item includes `created_at` (when the record was written) and `occurred_at` (when the event happened), and the timeline is ordered by `occurred_at` descending. Supports filtering by activity type, team member, job, date range (created_at_gte / created_at_lte), and text search.\n\n**When to use**: Use this for full activity pagination with filtering. You can also pass `include=activities` when calling `GET /v1/persons/{id}` for a simpler response.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person ID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Keyword search across activity content (whole words; matches any term). A match returns activity_content_match — the passage where the terms cluster." }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Comma-separated team member UUIDs to filter by activity creator/owner. Get IDs from GET /v1/team-members." }, "required": false, "name": "team_member_ids", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Comma-separated job UUIDs to filter activities by associated job. Get IDs from POST /v1/jobs/search." }, "required": false, "name": "job_ids", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Comma-separated activity types to include. Valid values — Notes: primary_note, secondary_note, interview_note, call_note, meeting_note, client_note, client_created_note, candidate_summary, meeting_transcript, client_rating. Communication: email, email_response, linkedin_message, linkedin_message_response, text_message. Synthetic: task, calendar_event, sequence_enrollment, pipeline_status, assessment. Example: \"email,secondary_note,task\"." }, "required": false, "name": "activity_types", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Comma-separated activity types to exclude. Accepts the same values as activity_types. Example: \"pipeline_status,assessment\"." }, "required": false, "name": "excluded_activity_types", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Comma-separated stage UUIDs to filter pipeline_status activities. Get IDs from GET /v1/jobs/{id} → pipeline_stages." }, "required": false, "name": "pipeline_stage_ids", "in": "query" }, { "schema": { "type": "string", "description": "Return only activities created at or after this timestamp (ISO 8601). Example: \"2026-03-22T00:00:00Z\". Use with created_at_lte for a date range." }, "required": false, "name": "created_at_gte", "in": "query" }, { "schema": { "type": "string", "description": "Return only activities created at or before this timestamp (ISO 8601). Example: \"2026-03-28T23:59:59Z\". Use with created_at_gte for a date range." }, "required": false, "name": "created_at_lte", "in": "query" } ], "responses": { "200": { "description": "Activities fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonActivitiesResponse" }, "example": { "success": true, "data": [ { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } }, { "id": "903e4567-0123-4567-890a-bcdef0123456", "activity_type": "email_response", "created_at": "2024-01-13T14:30:00Z", "occurred_at": "2024-01-13T14:30:00Z", "updated_at": "2024-01-13T14:30:00Z", "activity_content": "Thanks Jane! I am interested, lets schedule a call.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Re: Following up — Senior SWE role", "from_email": "john@techcorp.com", "to_email": "jane@startup.xyz", "status": "replied" } }, { "id": "ddd44444-eeee-ffff-0000-111111114444", "activity_type": "task", "created_at": "2024-01-12T09:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-12T09:30:00Z", "activity_content": "Schedule technical interview with John", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "task_details": { "status": "open", "due_date": "2024-01-20T17:00:00Z", "task_type": "follow_up", "assigned_to": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" } } }, { "id": "ccc33333-dddd-eeee-ffff-000000003333", "activity_type": "calendar_event", "created_at": "2024-01-18T14:00:00Z", "occurred_at": "2024-01-18T14:00:00Z", "updated_at": "2024-01-18T14:00:00Z", "activity_content": "Technical Interview — John Doe", "team_member": null, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "calendar_event_details": { "start_time": "2024-01-18T14:00:00Z", "end_time": "2024-01-18T15:00:00Z", "location": "Google Meet", "description": "Technical screen for Senior SWE position.", "conferencing": { "provider": "Google Meet", "url": "https://meet.google.com/abc-defg-hij" }, "is_shadow_invite": false } }, { "id": "eee55555-ffff-0000-1111-222222225555", "activity_type": "sequence_enrollment", "created_at": "2024-01-10T08:00:00Z", "occurred_at": "2024-01-10T08:00:00Z", "updated_at": "2024-01-10T08:00:00Z", "activity_content": "Enrolled in Outreach Campaign Q1 — active", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "sequence_enrollment_details": { "sequence_id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "sequence_name": "Outreach Campaign Q1", "status": "active" } }, { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "00077777-1111-2222-3333-444444447777", "activity_type": "assessment", "created_at": "2024-01-19T11:30:00Z", "occurred_at": "2024-01-19T11:30:00Z", "updated_at": "2024-01-19T11:30:00Z", "activity_content": "Technical Assessment — 4/5", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "assessment_details": { "score": 4, "template_name": "Technical Assessment", "template_id": "bbb22222-cccc-dddd-eeee-ffffffff2222", "rating_scale": 5, "assessor": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "assessment_content": "Strong candidate for the role. Problem Solving: Strong analytical skills. Communication: Clear and concise.", "overall_comment": { "content_text": "Strong candidate for the role." }, "criteria": [ { "id": "eee55555-6666-7777-8888-999999990001", "name": "Problem Solving", "importance": "must_have", "position": 1, "rating": 4, "comment": { "content_text": "Strong analytical skills." } }, { "id": "eee55555-6666-7777-8888-999999990002", "name": "Communication", "importance": "nice_to_have", "position": 2, "rating": 5, "comment": { "content_text": "Clear and concise." } } ] } }, { "id": "11188888-2222-3333-4444-555555558888", "activity_type": "linkedin_message", "created_at": "2024-01-09T15:00:00Z", "occurred_at": "2024-01-09T15:00:00Z", "updated_at": "2024-01-09T15:00:00Z", "activity_content": "Hi John, I came across your profile and would love to connect.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "22299999-3333-4444-5555-66666666aaaa", "activity_type": "client_rating", "created_at": "2024-01-20T09:00:00Z", "occurred_at": "2024-01-20T09:00:00Z", "updated_at": "2024-01-20T09:00:00Z", "activity_content": "4 stars", "team_member": null, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "333aaaaa-4444-5555-6666-77777777bbbb", "activity_type": "candidate_summary", "created_at": "2024-01-11T12:00:00Z", "occurred_at": "2024-01-11T12:00:00Z", "updated_at": "2024-01-11T12:00:00Z", "activity_content": "Strong backend engineer with 8 years of experience in distributed systems.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "444bbbbb-5555-6666-7777-88888888cccc", "activity_type": "whatsapp_message_response", "created_at": "2024-01-15T10:31:00Z", "occurred_at": "2024-01-15T10:31:00Z", "updated_at": "2024-01-15T10:31:00Z", "activity_content": "Thanks, I can talk Thursday afternoon.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": null, "whatsapp_details": { "conversation_id": "111e2345-e67f-89a0-b123-456789012345", "direction": "inbound", "is_deleted": false, "occurred_at": "2024-01-15T10:31:00Z", "text": "Thanks, I can talk Thursday afternoon." } }, { "id": "3f2c8a1e-5b7d-4c9e-8a1f-2d3e4f5a6b7c", "activity_type": "person_reference", "created_at": "2024-01-21T16:20:00Z", "occurred_at": "2024-01-20T15:00:00Z", "updated_at": "2024-01-21T16:20:00Z", "activity_content": "Reference (Previous Manager) with Jane Smith\nWould hire him again for any platform role.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": null, "person_reference_details": { "reference_id": "3f2c8a1e-5b7d-4c9e-8a1f-2d3e4f5a6b7c", "reference_type": "previous_manager", "reference_type_name": "Previous Manager", "reference_strength": "high", "direction": "outgoing", "related_person": { "id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith" }, "note": "Would hire him again for any platform role." } } ], "meta": { "total": 48, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/documents": { "get": { "operationId": "getPersonDocuments", "summary": "Get person documents", "description": "Retrieve a paginated list of documents (resumes, cover letters, transcripts, work samples, assessments, etc.) for a person. Each document has a stable unique id and a short-lived signed download URL that expires in minutes — re-fetch if the link expires. Pass include_text=true to also receive extracted plain-text content for reading or summarizing document contents. Optionally filter to specific document types via document_types (comma-separated type keys).", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person ID" } }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "default": false, "description": "When true, each document includes its extracted plain-text content (text_content, char_count, truncated). Useful for reading resumes, cover letters, transcripts, etc. Omit or pass false to receive only metadata and signed download links." }, "required": false, "name": "include_text", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated list of document type keys to filter by. Seeded values: resume_doc, resume_link, cover_letter, reference, additional_links, transcript, work_sample, offer_letter, assessment, other. Omit to return all types." }, "required": false, "name": "document_types", "in": "query" } ], "responses": { "200": { "description": "Documents fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDocumentsResponse" }, "example": { "success": true, "data": [ { "id": "eee55555-ffff-0000-1111-222222225555", "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-02T12:00:00Z", "type": "resume_doc", "title": "John_Doe_Resume.pdf", "link": "https://signed-url.example.com/...", "text_content": "John Doe\nSoftware Engineer\n\nExperience\nSenior Engineer at Acme Corp (2020–Present)\n- Led platform migration...", "char_count": 112, "truncated": false }, { "id": "fff66666-0000-1111-2222-333333336666", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "type": "cover_letter", "title": "Cover_Letter.pdf", "link": "https://signed-url.example.com/...", "text_content": "Dear Hiring Manager, I am excited to apply for the Senior Engineer role...", "char_count": 76, "truncated": false } ], "meta": { "total": 2, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "uploadPersonDocument", "summary": "Upload person document", "description": "Upload a document (resume, cover letter, etc.) for a person. Supports two modes:\n\n**1. Direct file upload** (`Content-Type: multipart/form-data`):\nSend the file in a `file` field along with metadata fields (`title`, `type`, `visible_in_share_links`).\nAllowed file types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB.\n\n**2. JSON body** (`Content-Type: application/json`):\nProvide a `file_url` — a publicly accessible HTTPS URL. The server downloads the file, validates it, and stores it.\n\nWhen `type` is `resume_doc` and AI auto-tagging is turned on for the workspace, the resume text is read in the background and used to fill the person's AI-enabled custom fields. The upload response does not wait for this.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person ID" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentUploadMultipart" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadRequest" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" }, "example": { "success": true, "data": { "id": "eee55555-ffff-0000-1111-222222225555", "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-01T10:00:00Z", "type": "resume_doc", "title": "John_Doe_Resume.pdf", "link": "https://signed-url.example.com/...", "visible_in_share_links": false } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/document-types": { "get": { "operationId": "listPersonDocumentTypes", "summary": "List person document types", "description": "Returns every active person document type for the organization, ordered by name. No pagination — the full list is always returned.\n\nDocument types are configurable per organization, so the available keys differ between organizations. Call this to discover valid `document_types` values for `POST /v1/persons/search` and `GET /v1/persons/{id}/documents`, and valid `type` values when uploading a document.", "tags": [ "Persons" ], "responses": { "200": { "description": "Document types fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDocumentTypesResponse" }, "example": { "success": true, "data": [ { "type": "resume_doc", "name": "Resume" }, { "type": "cover_letter", "name": "Cover Letter" }, { "type": "reference", "name": "Reference" }, { "type": "resume_link", "name": "Resume Link" }, { "type": "additional_links", "name": "Additional Links" }, { "type": "transcript", "name": "Transcript" }, { "type": "work_sample", "name": "Work Sample" }, { "type": "offer_letter", "name": "Offer Letter" }, { "type": "assessment", "name": "Assessment" }, { "type": "other", "name": "Other" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/preferred-email": { "post": { "operationId": "setPersonsPreferredEmail", "summary": "Set preferred email (bulk)", "description": "Star a stored email as preferred for one or many persons. Campaign enrollment uses the preferred email when it is set.\n\nThe email must already exist on each person — this endpoint does not add new addresses. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins.\n\nFor a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-email`.", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredEmailsBulkRequest" } } } }, "responses": { "200": { "description": "Preferred emails updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredEmailsBulkResponse" }, "example": { "success": true, "data": { "updated": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "preferred_email": "john@gmail.com" } ], "failed": [ { "person_id": "00000000-0000-0000-0000-000000000001", "error": "Person not found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/preferred-phone": { "post": { "operationId": "setPersonsPreferredPhone", "summary": "Set preferred phone (bulk)", "description": "Star a stored phone number as preferred for one or many persons.\n\nThe phone number must already exist on each person — this endpoint does not add new numbers. Formatting differences are accepted when the digits match. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins.\n\nFor a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-phone`.", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredPhonesBulkRequest" } } } }, "responses": { "200": { "description": "Preferred phones updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredPhonesBulkResponse" }, "example": { "success": true, "data": { "updated": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "preferred_phone": "+1-555-0123" } ], "failed": [ { "person_id": "00000000-0000-0000-0000-000000000001", "error": "Person not found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/email-bounced": { "post": { "operationId": "setPersonsEmailBounced", "summary": "Mark emails as bounced (bulk)", "description": "Mark or unmark stored email addresses as bounced for one or many persons. Emails and campaigns skip bounced addresses, and the address stays on the person.\n\nEach address must already exist on its person; matching ignores letter case. Several addresses of the same person can be sent in one request. Invalid rows fail individually and do not block other rows in the same request. When the same person_id and email appear twice, the last entry wins.\n\nRead the current state from `is_bounced` on each `emails[]` entry of a person response.", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEmailsBouncedBulkRequest" } } } }, "responses": { "200": { "description": "Bounced flags updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEmailsBouncedBulkResponse" }, "example": { "success": true, "data": { "updated": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "email": "john@techcorp.com", "is_bounced": true } ], "failed": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "email": "old@techcorp.com", "error": "Email is not stored on this person" }, { "person_id": "00000000-0000-0000-0000-000000000001", "email": "jane@example.com", "error": "Person not found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/emails/delete": { "post": { "operationId": "deletePersonsEmails", "summary": "Remove emails (bulk)", "description": "Remove individual stored email addresses from one or many persons. Only the named address is removed; the person's other emails and phone numbers stay.\n\nEach address must already exist on its person; matching ignores letter case. If the removed address was the preferred email, no other address is starred in its place; use `POST /v1/persons/preferred-email` to choose one. Invalid rows fail individually and do not block other rows in the same request. This cannot be undone.", "tags": [ "Persons" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEmailsBulkRequest" } } } }, "responses": { "200": { "description": "Emails removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEmailsBulkResponse" }, "example": { "success": true, "data": { "deleted": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "email": "john@gmail.com" } ], "failed": [ { "person_id": "123e4567-e89b-12d3-a456-426614174000", "email": "old@techcorp.com", "error": "Email is not stored on this person" }, { "person_id": "00000000-0000-0000-0000-000000000001", "email": "jane@example.com", "error": "Person not found" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/preferred-email": { "post": { "operationId": "setPersonPreferredEmail", "summary": "Set preferred email", "description": "Star a stored email as this person's preferred address and return the updated person. Campaign enrollment uses the preferred email when it is set.\n\nThe email must already exist on the person. To update many people in one request, use `POST /v1/persons/preferred-email`.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredEmailRequest" } } } }, "responses": { "200": { "description": "Preferred email set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonByIdResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "external_source_id": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:45:00.000Z", "image_url": "https://media.samplecdn.com/dms/image/example.jpg", "location": "San Francisco, CA", "latitude": 37.7749, "longitude": -122.4194, "date_of_last_engagement": "2024-06-18T09:00:00.000Z", "last_activity_type": "email", "do_not_contact": false, "do_not_contact_reason": null, "do_not_contact_expiration_date": null, "owner_id": null, "preferred_email": "john@techcorp.com", "preferred_phone": "+1-555-0123", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com", "is_preferred": true, "is_bounced": false }, { "contact_data_type": "personal", "value": "john@gmail.com", "is_preferred": false, "is_bounced": false } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123", "is_preferred": true } ], "work_experience": [ { "company_name": "Tech Corp", "company_linkedin_url": "https://www.linkedin.com/company/techcorp", "company_linkedin_id": 12345678, "company_id": "456e7890-e12b-34d5-a678-901234567890", "duration_in_months": 36, "positions": [ { "title": "Software Engineer", "start_date": "2022-01-01", "end_date": null, "duration_in_months": 36, "description": "Full-stack development", "location": "San Francisco, CA", "position_type": "Full-time" } ] } ], "education_experience": [ { "company_name": "Stanford University", "start_date": "2016-09-01", "end_date": "2020-06-01", "description": null, "degree": "B.S. Computer Science", "company_linkedin_url": "https://www.linkedin.com/school/stanford", "company_linkedin_id": 1234, "company_id": null } ], "certifications": [ { "name": "AWS Solutions Architect", "credential_id": "AWS-SA-001", "start_date": "2023-06-01", "end_date": "2026-06-01", "company_name": "Amazon Web Services", "company_linkedin_url": null, "company_linkedin_id": null, "company_id": null } ], "candidates": [ { "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "job_name": "Senior Software Engineer", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_client_company_name": "StartupXYZ", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "is_archived": false, "created_at": "2024-01-12T14:30:00Z", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "owner_id": null } ], "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attribute_name": "Seniority Level", "data_type": "single-select", "value": null, "tag": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Senior" }, "team_member": null, "company": null }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "attribute_name": "Years of Experience", "data_type": "decimal", "value": 8, "tag": null, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Tech Corp" } } ], "activities": [ { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } } ], "compensation": [ { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "actual", "currency_code": "USD", "current_compensation_base": 180000, "current_compensation_bonus": 20000, "bonus_percent": null, "equity_percent": null, "equity_amount": 50000, "compensation_year": 2024, "total_estimated_compensation": 250000, "note": "Current package at Tech Corp", "job_id": null, "job_name": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "related_people": [ { "relation_id": "rel-1111-2222-3333-444444444444", "person_id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "Engineering Manager", "linkedin_public_id": "janesmith", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "relation_type": "colleague", "relation_type_name": "Colleague", "relation_strength": "medium", "note": "Worked together on Platform team", "note_html": "

Worked together on Platform team

", "direction": "outgoing", "occurred_at": "2024-01-04T15:00:00Z", "created_at": "2024-01-05T10:00:00Z" } ], "offers": [ { "id": "offer-1111-2222-3333-444444444444", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_name": "Senior Software Engineer", "job_company_name": "StartupXYZ", "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "status": { "id": "status-1111", "name": "Extended", "color": "#22c55e", "status_type": "pending" }, "extended_date": "2024-02-01T00:00:00Z", "accepted_date": null, "candidate_start_date": "2024-03-01T00:00:00Z", "compensation_currency": "USD", "compensation_base": 200000, "compensation_bonus": 30000, "bonus_type": "fixed", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": null, "initial_equity_grant_amount": 100000, "relocation_bonus": 10000, "sign_on_bonus": 25000, "total_estimated_compensation": 315000, "note": "Competitive offer with strong equity component", "created_at": "2024-02-01T00:00:00Z", "updated_at": "2024-02-01T00:00:00Z" } ], "team_connections": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "is_former_member": false, "strength": "high", "linkedin_connected_on": "2021-08-18" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/preferred-phone": { "post": { "operationId": "setPersonPreferredPhone", "summary": "Set preferred phone", "description": "Star a stored phone number as this person's preferred number and return the updated person.\n\nThe phone number must already exist on the person. Formatting differences are accepted when the digits match. To update many people in one request, use `POST /v1/persons/preferred-phone`.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredPhoneRequest" } } } }, "responses": { "200": { "description": "Preferred phone set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonByIdResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "external_source_id": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:45:00.000Z", "image_url": "https://media.samplecdn.com/dms/image/example.jpg", "location": "San Francisco, CA", "latitude": 37.7749, "longitude": -122.4194, "date_of_last_engagement": "2024-06-18T09:00:00.000Z", "last_activity_type": "email", "do_not_contact": false, "do_not_contact_reason": null, "do_not_contact_expiration_date": null, "owner_id": null, "preferred_email": "john@techcorp.com", "preferred_phone": "+1-555-0123", "emails": [ { "contact_data_type": "work", "value": "john@techcorp.com", "is_preferred": true, "is_bounced": false }, { "contact_data_type": "personal", "value": "john@gmail.com", "is_preferred": false, "is_bounced": false } ], "phones": [ { "contact_data_type": "mobile", "value": "+1-555-0123", "is_preferred": true } ], "work_experience": [ { "company_name": "Tech Corp", "company_linkedin_url": "https://www.linkedin.com/company/techcorp", "company_linkedin_id": 12345678, "company_id": "456e7890-e12b-34d5-a678-901234567890", "duration_in_months": 36, "positions": [ { "title": "Software Engineer", "start_date": "2022-01-01", "end_date": null, "duration_in_months": 36, "description": "Full-stack development", "location": "San Francisco, CA", "position_type": "Full-time" } ] } ], "education_experience": [ { "company_name": "Stanford University", "start_date": "2016-09-01", "end_date": "2020-06-01", "description": null, "degree": "B.S. Computer Science", "company_linkedin_url": "https://www.linkedin.com/school/stanford", "company_linkedin_id": 1234, "company_id": null } ], "certifications": [ { "name": "AWS Solutions Architect", "credential_id": "AWS-SA-001", "start_date": "2023-06-01", "end_date": "2026-06-01", "company_name": "Amazon Web Services", "company_linkedin_url": null, "company_linkedin_id": null, "company_id": null } ], "candidates": [ { "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "job_name": "Senior Software Engineer", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_client_company_name": "StartupXYZ", "current_pipeline_stage_name": "Technical Interview", "current_pipeline_stage_id": "567e8901-e23c-45d6-e789-012345678901", "is_archived": false, "created_at": "2024-01-12T14:30:00Z", "sourced_by": "234e5678-e90a-12b3-c456-789012345678", "owner_id": null } ], "custom_fields": [ { "attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attribute_name": "Seniority Level", "data_type": "single-select", "value": null, "tag": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Senior" }, "team_member": null, "company": null }, { "attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "attribute_name": "Years of Experience", "data_type": "decimal", "value": 8, "tag": null, "team_member": null, "company": null }, { "attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "attribute_name": "Referred By", "data_type": "multi-company", "value": null, "tag": null, "team_member": null, "company": { "id": "456e7890-e12b-34d5-a678-901234567890", "name": "Tech Corp" } } ], "activities": [ { "id": "fff66666-0000-1111-2222-333333336666", "activity_type": "pipeline_status", "created_at": "2024-01-15T10:00:00Z", "occurred_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "activity_content": "Moved to Technical Interview", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "pipeline_status_details": { "stage_name": "Technical Interview", "is_rejection_stage": false, "entered_at": "2024-01-15T10:00:00Z", "exited_at": null, "reason_text": null, "rejection_reason": null } }, { "id": "901e2345-e67f-89a0-b123-456789012345", "activity_type": "secondary_note", "created_at": "2024-01-14T16:00:00Z", "occurred_at": "2024-01-12T09:00:00Z", "updated_at": "2024-01-14T16:45:00Z", "activity_content": "Great initial call. Strong system design skills.", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" } }, { "id": "902e3456-f78a-90b1-c234-567890123456", "activity_type": "email", "created_at": "2024-01-13T11:00:00Z", "occurred_at": "2024-01-13T11:00:00Z", "updated_at": "2024-01-13T11:00:00Z", "activity_content": "Hi John, following up on our conversation...", "team_member": { "id": "234e5678-e90a-12b3-c456-789012345678", "name": "Jane Smith" }, "job": { "id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "StartupXYZ" }, "email_details": { "subject": "Following up — Senior SWE role", "from_email": "jane@startup.xyz", "to_email": "john@techcorp.com", "status": "sent" } } ], "compensation": [ { "id": "678e9012-e34d-56f7-a890-123456789012", "compensation_type": "actual", "currency_code": "USD", "current_compensation_base": 180000, "current_compensation_bonus": 20000, "bonus_percent": null, "equity_percent": null, "equity_amount": 50000, "compensation_year": 2024, "total_estimated_compensation": 250000, "note": "Current package at Tech Corp", "job_id": null, "job_name": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "related_people": [ { "relation_id": "rel-1111-2222-3333-444444444444", "person_id": "567e8901-e23c-45d6-e789-012345678901", "name": "Jane Smith", "current_job_title": "Engineering Manager", "linkedin_public_id": "janesmith", "current_company_name": "Tech Corp", "current_company_id": "456e7890-e12b-34d5-a678-901234567890", "relation_type": "colleague", "relation_type_name": "Colleague", "relation_strength": "medium", "note": "Worked together on Platform team", "note_html": "

Worked together on Platform team

", "direction": "outgoing", "occurred_at": "2024-01-04T15:00:00Z", "created_at": "2024-01-05T10:00:00Z" } ], "offers": [ { "id": "offer-1111-2222-3333-444444444444", "job_id": "345e6789-e01b-23c4-d567-890123456789", "job_name": "Senior Software Engineer", "job_company_name": "StartupXYZ", "candidate_id": "789e0123-e45f-67a8-b901-234567890123", "status": { "id": "status-1111", "name": "Extended", "color": "#22c55e", "status_type": "pending" }, "extended_date": "2024-02-01T00:00:00Z", "accepted_date": null, "candidate_start_date": "2024-03-01T00:00:00Z", "compensation_currency": "USD", "compensation_base": 200000, "compensation_bonus": 30000, "bonus_type": "fixed", "annual_equity_grant_percent": null, "annual_equity_grant_amount": 50000, "initial_equity_grant_percent": null, "initial_equity_grant_amount": 100000, "relocation_bonus": 10000, "sign_on_bonus": 25000, "total_estimated_compensation": 315000, "note": "Competitive offer with strong equity component", "created_at": "2024-02-01T00:00:00Z", "updated_at": "2024-02-01T00:00:00Z" } ], "team_connections": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "team_member_name": "Jane Smith", "is_former_member": false, "strength": "high", "linkedin_connected_on": "2021-08-18" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/persons/{id}/enrich": { "post": { "operationId": "enrichPersonContact", "summary": "Enrich person contact details", "description": "Look up email (and phone, when enabled) contact details for a person via Stardex enrichment providers.\n\n**Organization gate**: requires `enrichment_api_enabled` on the organization (staff-enabled).\n\n**Quota**: organization-wide limit of 500 enrichment requests per active team member with an `auth_user_id`, per UTC calendar month. Quota usage is returned in the response body and in `X-Enrichment-Quota-*` headers.\n\n**API-key scope**: `persons:write`.", "tags": [ "Persons" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Person UUID" } } ], "responses": { "200": { "description": "Contact details enriched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonContactEnrichmentResponse" }, "example": { "success": true, "data": { "person_id": "123e4567-e89b-12d3-a456-426614174000", "linkedin_public_id": "johndoe", "linkedin_url": "https://www.linkedin.com/in/johndoe", "emails": [ { "value": "john@example.com", "contact_data_type": "personal", "source": "rocketreach", "priority": 1 }, { "value": "john@techcorp.com", "contact_data_type": "work", "source": "apollo", "priority": 2 } ], "phones": [ { "value": "+1-555-0123", "contact_data_type": "mobile", "source": "signalhire", "priority": 1 }, { "value": "+1-555-0199", "contact_data_type": "work", "source": "fullenrich", "priority": 2 }, { "value": "+1-555-0142", "contact_data_type": "home", "source": "pdl", "priority": 3 } ], "quota": { "allowed": true, "used": 12, "limit": 1500, "remaining": 1488, "billable_member_count": 3, "per_member_limit": 500, "period_start": "2026-09-01", "resets_at": "2026-10-01T00:00:00.000Z" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs": { "get": { "operationId": "listRetainerPacks", "summary": "List retainer packs", "description": "A retainer pack is a set of retainers sold to a client company on one invoice. Each placement at that client claims the next open retainer, which is deducted from what the placement bills. Placements claim retainers when they are logged in the app.\n\n**Filters**: `organization_company_id` and `is_closed` (`false` returns the packs offered when logging a placement).\n\n**Sorting**: newest first.\n\n**Pagination**: `offset` and `limit` (default 20, max 100).\n\nA retainer claimed by a placement on a confidential job you cannot see shows `claim.is_restricted: true` with only the placement ID.\n\n**Access**: Everyone in the workspace can read retainer packs. API keys need the `fees:read` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only return packs for this client company." }, "required": false, "description": "Only return packs for this client company.", "name": "organization_company_id", "in": "query" }, { "schema": { "type": "boolean", "description": "`false` returns open packs only (the ones offered when logging a placement), `true` closed packs only. Omit for both." }, "required": false, "description": "`false` returns open packs only (the ones offered when logging a placement), `true` closed packs only. Omit for both.", "name": "is_closed", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "description": "Records to skip for pagination. Defaults to 0.", "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max records per page (1-100). Defaults to 20." }, "required": false, "description": "Max records per page (1-100). Defaults to 20.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Retainer packs fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPacksListResponse" }, "example": { "success": true, "data": [ { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" }, { "id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "H1 2026 leadership pack", "currency_code": "EUR", "invoice_number": "INV-0981", "link_extra_hires": true, "firm_commission_percent": 0, "is_closed": true, "closed_at": "2026-07-01T10:00:00.000Z", "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-01-15", "actual_payment_date": "2026-02-01", "amount_each": 10000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100 } ], "retainers": [ { "id": "5f6a7b8c-9d0e-4f1a-8b2c-4d5e6f7a8b9c", "position": 1, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b", "job_id": "6a7b8c9d-0e1f-4a2b-9c3d-5e6f7a8b9c0d", "job_title": "Chief Financial Officer", "candidate_id": "7b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d1e", "person_id": "8c9d0e1f-2a3b-4c4d-9e5f-7a8b9c0d1e2f", "person_name": "Priya Shah", "start_date": "2026-03-02" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] }, { "id": "6a7b8c9d-0e1f-4a2b-8c3d-5e6f7a8b9c0e", "position": 2, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "2f3a4b5c-6d7e-4f8a-9b9c-0d1e2f3a4b5c", "job_id": "9d0e1f2a-3b4c-4d5e-8f6a-8b9c0d1e2f3a", "job_title": "Head of Sales", "candidate_id": "0e1f2a3b-4c5d-4e6f-9a7b-9c0d1e2f3a4b", "person_id": "1f2a3b4c-5d6e-4f7a-8b8c-0d1e2f3a4b5c", "person_name": "Marcus Webb", "start_date": "2026-04-13" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] } ], "extra_hires": [ { "placement_fee_event_id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d", "job_id": "2a3b4c5d-6e7f-4a8b-9c9d-1e2f3a4b5c6e", "job_title": "VP of Marketing", "candidate_id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "person_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "person_name": "Elena Novak", "start_date": "2026-06-01" } ], "adjustments": [ { "id": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a", "amount": 2500, "comment": "Goodwill credit after a guarantee replacement", "adjusted_on": "2026-07-01", "created_at": "2026-07-01T10:00:00.000Z" } ], "summary": { "retainer_count": 2, "claimed_count": 2, "open_count": 0, "extra_hire_count": 1, "total_amount": 20000, "remaining_amount": 0, "adjustments_total": 2500, "net_retained": 17500 }, "created_at": "2026-01-10T08:30:00.000Z", "updated_at": "2026-07-01T10:00:00.000Z" } ], "meta": { "total": 2, "offset": 0, "limit": 20 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "operationId": "createRetainerPack", "summary": "Create a retainer pack", "description": "Creates a pack of `retainer_count` open retainers of `amount_each` for a client company, all on one invoice. Amounts are per retainer. Every retainer shares the pack status, invoice date and currency.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetainerPackBody" } } } }, "responses": { "201": { "description": "Retainer pack created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "The company is not a client, more than 100 retainers, splits not totalling 100%, or an unknown fee status or team member", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}": { "get": { "operationId": "getRetainerPack", "summary": "Get a retainer pack", "description": "Returns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Everyone in the workspace can read retainer packs. API keys need the `fees:read` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "responses": { "200": { "description": "Retainer pack fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateRetainerPack", "summary": "Update a retainer pack", "description": "Changes only the fields you send. To top up a pack, send `add_retainers`: that many open retainers are added to the same pack and invoice. A new amount or split applies to open retainers; claimed retainers keep theirs. Status and invoice date apply to every retainer.\n\nOnce a pack is paid, only admins can change its amount, firm commission, currency or split, lower `retainer_count`, or move it back to an unpaid status.\n\nA closed pack keeps its retainer count, amount, firm commission and currency: reopen it to change them.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRetainerPackBody" } } } }, "responses": { "200": { "description": "Retainer pack updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "Currency can't change after a retainer is claimed (`RETAINER_PACK_CURRENCY_LOCKED`), or the pack is closed (`RETAINER_PACK_CLOSED`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "Fewer retainers than are claimed, more than 100 retainers, or splits not totalling 100%", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteRetainerPack", "summary": "Delete a retainer pack", "description": "Deletes the pack, its open retainers and its adjustments. A pack with claimed retainers cannot be deleted: the `409` response lists the claiming placements in `error.details.claimed_placements`; unlink them in the app first.\n\n**Access**: Session and OAuth callers must be organization admins (`org:admin`). API keys need the `fees:delete` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "responses": { "200": { "description": "Retainer pack deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Retainer pack deleted" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "Retainers in the pack are claimed by placements", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "example": { "success": false, "error": { "code": "RETAINER_PACK_HAS_CLAIMED_RETAINERS", "message": "2 retainers in this pack are claimed. Unlink these placements, then delete the pack.", "details": { "claimed_placements": [ { "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "retainer_id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e" }, { "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a", "retainer_id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f" } ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/close": { "post": { "operationId": "closeRetainerPack", "summary": "Close a retainer pack", "description": "Closed packs are no longer offered when logging placements. The pack status does not change. Optionally records a refund for unclaimed retainers as an adjustment.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseRetainerPackBody" } } } }, "responses": { "200": { "description": "Retainer pack closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "H1 2026 leadership pack", "currency_code": "EUR", "invoice_number": "INV-0981", "link_extra_hires": true, "firm_commission_percent": 0, "is_closed": true, "closed_at": "2026-07-01T10:00:00.000Z", "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-01-15", "actual_payment_date": "2026-02-01", "amount_each": 10000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100 } ], "retainers": [ { "id": "5f6a7b8c-9d0e-4f1a-8b2c-4d5e6f7a8b9c", "position": 1, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b", "job_id": "6a7b8c9d-0e1f-4a2b-9c3d-5e6f7a8b9c0d", "job_title": "Chief Financial Officer", "candidate_id": "7b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d1e", "person_id": "8c9d0e1f-2a3b-4c4d-9e5f-7a8b9c0d1e2f", "person_name": "Priya Shah", "start_date": "2026-03-02" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] }, { "id": "6a7b8c9d-0e1f-4a2b-8c3d-5e6f7a8b9c0e", "position": 2, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "2f3a4b5c-6d7e-4f8a-9b9c-0d1e2f3a4b5c", "job_id": "9d0e1f2a-3b4c-4d5e-8f6a-8b9c0d1e2f3a", "job_title": "Head of Sales", "candidate_id": "0e1f2a3b-4c5d-4e6f-9a7b-9c0d1e2f3a4b", "person_id": "1f2a3b4c-5d6e-4f7a-8b8c-0d1e2f3a4b5c", "person_name": "Marcus Webb", "start_date": "2026-04-13" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] } ], "extra_hires": [ { "placement_fee_event_id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d", "job_id": "2a3b4c5d-6e7f-4a8b-9c9d-1e2f3a4b5c6e", "job_title": "VP of Marketing", "candidate_id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "person_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "person_name": "Elena Novak", "start_date": "2026-06-01" } ], "adjustments": [ { "id": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a", "amount": 2500, "comment": "Goodwill credit after a guarantee replacement", "adjusted_on": "2026-07-01", "created_at": "2026-07-01T10:00:00.000Z" } ], "summary": { "retainer_count": 2, "claimed_count": 2, "open_count": 0, "extra_hire_count": 1, "total_amount": 20000, "remaining_amount": 0, "adjustments_total": 2500, "net_retained": 17500 }, "created_at": "2026-01-10T08:30:00.000Z", "updated_at": "2026-07-01T10:00:00.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The pack is already closed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "Refund amount not above 0, or more than the unclaimed retainers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/reopen": { "post": { "operationId": "reopenRetainerPack", "summary": "Reopen a retainer pack", "description": "Placements at the client are offered this pack again. Reopening an open pack changes nothing. A pack with a refund or other adjustment cannot be reopened: delete the adjustment first.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "responses": { "200": { "description": "Retainer pack reopened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The pack has a refund or adjustment (`RETAINER_PACK_HAS_REFUND`). Delete it before reopening", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/adjustments": { "post": { "operationId": "addRetainerPackAdjustment", "summary": "Add an adjustment to a closed retainer pack", "description": "Records money returned on a closed pack, such as a refund. It shows as a negative line and lowers the net retained amount. Revenue reports do not count adjustments.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetainerPackAdjustmentBody" } } } }, "responses": { "200": { "description": "Adjustment added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "H1 2026 leadership pack", "currency_code": "EUR", "invoice_number": "INV-0981", "link_extra_hires": true, "firm_commission_percent": 0, "is_closed": true, "closed_at": "2026-07-01T10:00:00.000Z", "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-01-15", "actual_payment_date": "2026-02-01", "amount_each": 10000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100 } ], "retainers": [ { "id": "5f6a7b8c-9d0e-4f1a-8b2c-4d5e6f7a8b9c", "position": 1, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b", "job_id": "6a7b8c9d-0e1f-4a2b-9c3d-5e6f7a8b9c0d", "job_title": "Chief Financial Officer", "candidate_id": "7b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d1e", "person_id": "8c9d0e1f-2a3b-4c4d-9e5f-7a8b9c0d1e2f", "person_name": "Priya Shah", "start_date": "2026-03-02" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] }, { "id": "6a7b8c9d-0e1f-4a2b-8c3d-5e6f7a8b9c0e", "position": 2, "amount": 10000, "firm_commission_percent": 0, "claim": { "is_restricted": false, "placement_fee_event_id": "2f3a4b5c-6d7e-4f8a-9b9c-0d1e2f3a4b5c", "job_id": "9d0e1f2a-3b4c-4d5e-8f6a-8b9c0d1e2f3a", "job_title": "Head of Sales", "candidate_id": "0e1f2a3b-4c5d-4e6f-9a7b-9c0d1e2f3a4b", "person_id": "1f2a3b4c-5d6e-4f7a-8b8c-0d1e2f3a4b5c", "person_name": "Marcus Webb", "start_date": "2026-04-13" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 100, "split_amount": 10000 } ] } ], "extra_hires": [ { "placement_fee_event_id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d", "job_id": "2a3b4c5d-6e7f-4a8b-9c9d-1e2f3a4b5c6e", "job_title": "VP of Marketing", "candidate_id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "person_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "person_name": "Elena Novak", "start_date": "2026-06-01" } ], "adjustments": [ { "id": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a", "amount": 2500, "comment": "Goodwill credit after a guarantee replacement", "adjusted_on": "2026-07-01", "created_at": "2026-07-01T10:00:00.000Z" } ], "summary": { "retainer_count": 2, "claimed_count": 2, "open_count": 0, "extra_hire_count": 1, "total_amount": 20000, "remaining_amount": 0, "adjustments_total": 2500, "net_retained": 17500 }, "created_at": "2026-01-10T08:30:00.000Z", "updated_at": "2026-07-01T10:00:00.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "The pack is open, or the amount is not above 0 or more than the net retained", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/adjustments/{adjustment_id}": { "delete": { "operationId": "deleteRetainerPackAdjustment", "summary": "Delete a retainer pack adjustment", "description": "Net retained goes back up by the adjustment amount.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:delete` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } }, { "in": "path", "name": "adjustment_id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Adjustment ID" } } ], "responses": { "200": { "description": "Adjustment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/retainers/{retainer_id}": { "delete": { "operationId": "deletePackRetainer", "summary": "Delete an open retainer from a pack", "description": "Removes one open retainer, lowering the pack count by one. Claimed retainers and the last retainer of a pack cannot be deleted. Only admins can delete a retainer from a paid pack. Reopen a closed pack before deleting its retainers.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers need permission to edit CRM records (`org:crm:edit`; `org:admin` always can). API keys need the `fees:delete` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } }, { "in": "path", "name": "retainer_id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer ID" } } ], "responses": { "200": { "description": "Retainer deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "The retainer is claimed by a placement (`PACK_RETAINER_CLAIMED`), or the pack is closed (`RETAINER_PACK_CLOSED`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "The retainer is the last one in the pack", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/retainer-packs/{id}/retainers/{retainer_id}/split": { "put": { "operationId": "replacePackRetainerSplit", "summary": "Replace a claimed retainer's split", "description": "Replaces who gets credit for one claimed retainer. Open retainers use the pack's split; change it with `PATCH /v1/retainer-packs/{id}` instead.\n\nReturns the full pack with its retainers, claims, splits, extra hires, adjustments and summary.\n\n**Access**: Session and OAuth callers must be organization admins (`org:admin`). API keys need the `fees:write` scope.", "tags": [ "Retainer Packs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer pack ID" } }, { "in": "path", "name": "retainer_id", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Retainer ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePackRetainerSplitBody" } } } }, "responses": { "200": { "description": "Retainer split replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetainerPackResponse" }, "example": { "success": true, "data": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "organization_company_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_company_name": "Acme Corp", "name": "Q4 2026 GTM pack", "currency_code": "USD", "invoice_number": "INV-1042", "link_extra_hires": true, "firm_commission_percent": 10, "is_closed": false, "closed_at": null, "fee_status": { "id": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "name": "Paid", "status_type": "paid", "color": "#22c55e" }, "expected_date": "2026-10-01", "actual_payment_date": "2026-10-15", "amount_each": 12000, "default_split": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30 } ], "retainers": [ { "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "position": 1, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": false, "placement_fee_event_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "job_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "job_title": "VP of Engineering", "candidate_id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "person_id": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "person_name": "Jordan Lee", "start_date": "2026-11-03" }, "splits": [ { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": "Recruiter", "split_percentage": 60, "split_amount": 6480 }, { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 40, "split_amount": 4320 } ] }, { "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "position": 2, "amount": 12000, "firm_commission_percent": 10, "claim": { "is_restricted": true, "placement_fee_event_id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a" }, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] }, { "id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a", "position": 3, "amount": 12000, "firm_commission_percent": 10, "claim": null, "splits": [ { "team_member_id": "6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c", "team_member_name": "Theo Grant", "role": "Sales", "split_percentage": 70, "split_amount": 7560 }, { "team_member_id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d", "team_member_name": "Ana Ruiz", "role": null, "split_percentage": 30, "split_amount": 3240 } ] } ], "extra_hires": [], "adjustments": [], "summary": { "retainer_count": 3, "claimed_count": 2, "open_count": 1, "extra_hire_count": 0, "total_amount": 36000, "remaining_amount": 12000, "adjustments_total": 0, "net_retained": 36000 }, "created_at": "2026-09-28T09:12:44.000Z", "updated_at": "2026-10-15T16:03:10.000Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "You do not have permission to make this change", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "422": { "description": "The retainer is open, or the splits do not total 100%", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecard-templates/search": { "post": { "operationId": "searchScorecardTemplates", "summary": "Search scorecard templates", "description": "Search and filter scorecard templates (the assessment rubrics used to score candidates) with pagination and sorting.\n\n**Filters**: `keywords` (substring match on name or description), `job_id` (return templates scoped to a specific job — pair with `include_org_wide` to also include org-wide templates), `created_by_ids` (team members who created the template), `is_archived` (defaults to false).\n\n**Sorting**: `sort_by` — `created_at` (default), `updated_at`, or `name`. `sort_order` — `asc` or `desc` (default).\n\n**Pagination**: `offset` and `limit` (max 100).", "tags": [ "Scorecards" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplatesSearchBody" } } } }, "responses": { "200": { "description": "Scorecard templates found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplatesSearchResponse" }, "example": { "success": true, "data": [ { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "description": "Interview rubric for senior backend engineering candidates.", "job_id": "456e7890-e12b-34d5-a678-901234567890", "rating_scale": 5, "enable_ai_auto_grade": false, "is_archived": false, "overall_default_text": "Summarize the candidate against the must-have criteria first, then list any concerns.", "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "created_at": "2026-05-20T10:00:00Z", "updated_at": "2026-05-20T10:00:00Z", "criteria": [ { "id": "bbbb1111-2222-3333-4444-555555555555", "name": "System design depth", "description": "Can the candidate reason about consistency, partitioning, and failure modes for a multi-region service?", "importance": "must_have", "position": 1, "is_archived": false, "default_text": "Note specific systems they have built, scale handled, and trade-offs discussed." }, { "id": "cccc1111-2222-3333-4444-555555555555", "name": "Async collaboration", "description": "Quality of written communication and decision logs.", "importance": "nice_to_have", "position": 2, "is_archived": false, "default_text": null } ] } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecard-templates/{id}": { "get": { "operationId": "getScorecardTemplateById", "summary": "Get scorecard template by ID", "description": "Retrieve a single scorecard template by its UUID, including all criteria (active + archived).", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard template ID" } } ], "responses": { "200": { "description": "Scorecard template found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplateByIdResponse" }, "example": { "success": true, "data": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "description": "Interview rubric for senior backend engineering candidates.", "job_id": "456e7890-e12b-34d5-a678-901234567890", "rating_scale": 5, "enable_ai_auto_grade": false, "is_archived": false, "overall_default_text": "Summarize the candidate against the must-have criteria first, then list any concerns.", "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "created_at": "2026-05-20T10:00:00Z", "updated_at": "2026-05-20T10:00:00Z", "criteria": [ { "id": "bbbb1111-2222-3333-4444-555555555555", "name": "System design depth", "description": "Can the candidate reason about consistency, partitioning, and failure modes for a multi-region service?", "importance": "must_have", "position": 1, "is_archived": false, "default_text": "Note specific systems they have built, scale handled, and trade-offs discussed." }, { "id": "cccc1111-2222-3333-4444-555555555555", "name": "Async collaboration", "description": "Quality of written communication and decision logs.", "importance": "nice_to_have", "position": 2, "is_archived": false, "default_text": null } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateScorecardTemplate", "summary": "Update scorecard template", "description": "Update an existing scorecard template. Only provided fields are modified.\n\n**Criteria replacement**: when `criteria` is provided, existing active criteria are archived (preserving historical ratings) and the new criteria are inserted. Omit `criteria` to leave the criteria set unchanged.\n\n**Team member assignment**: `last_updated_by` is the calling team member. Pass `team_member_id` only when authenticating with an API key.", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard template ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplateUpdateRequest" } } } }, "responses": { "200": { "description": "Scorecard template updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplateUpdateResponse" }, "example": { "success": true, "data": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "description": "Interview rubric for senior backend engineering candidates.", "job_id": "456e7890-e12b-34d5-a678-901234567890", "rating_scale": 5, "enable_ai_auto_grade": false, "is_archived": false, "overall_default_text": "Summarize the candidate against the must-have criteria first, then list any concerns.", "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "created_at": "2026-05-20T10:00:00Z", "updated_at": "2026-05-20T10:00:00Z", "criteria": [ { "id": "bbbb1111-2222-3333-4444-555555555555", "name": "System design depth", "description": "Can the candidate reason about consistency, partitioning, and failure modes for a multi-region service?", "importance": "must_have", "position": 1, "is_archived": false, "default_text": "Note specific systems they have built, scale handled, and trade-offs discussed." }, { "id": "cccc1111-2222-3333-4444-555555555555", "name": "Async collaboration", "description": "Quality of written communication and decision logs.", "importance": "nice_to_have", "position": 2, "is_archived": false, "default_text": null } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteScorecardTemplate", "summary": "Archive scorecard template", "description": "Archives the scorecard template (soft delete) so it is hidden from selection. Past scorecards that reference this template remain readable.", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard template ID" } } ], "responses": { "200": { "description": "Scorecard template archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Scorecard template archived" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecard-templates": { "post": { "operationId": "createScorecardTemplate", "summary": "Create scorecard template", "description": "Create a new scorecard template (assessment rubric) with optional criteria.\n\n**Job scoping**: pass `job_id` to bind the template to a specific job in this team. Only one active template can exist per job in the team — archive the existing one before creating a new one.\n\n**Team member assignment**: the template is recorded as created by the calling team member. Pass `team_member_id` only when authenticating with an API key (no implicit member context). Session and OAuth callers cannot attribute creation to a different member.", "tags": [ "Scorecards" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplateCreateRequest" } } } }, "responses": { "201": { "description": "Scorecard template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardTemplateCreateResponse" }, "example": { "success": true, "data": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "description": "Interview rubric for senior backend engineering candidates.", "job_id": "456e7890-e12b-34d5-a678-901234567890", "rating_scale": 5, "enable_ai_auto_grade": false, "is_archived": false, "overall_default_text": "Summarize the candidate against the must-have criteria first, then list any concerns.", "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "created_at": "2026-05-20T10:00:00Z", "updated_at": "2026-05-20T10:00:00Z", "criteria": [ { "id": "bbbb1111-2222-3333-4444-555555555555", "name": "System design depth", "description": "Can the candidate reason about consistency, partitioning, and failure modes for a multi-region service?", "importance": "must_have", "position": 1, "is_archived": false, "default_text": "Note specific systems they have built, scale handled, and trade-offs discussed." }, { "id": "cccc1111-2222-3333-4444-555555555555", "name": "Async collaboration", "description": "Quality of written communication and decision logs.", "importance": "nice_to_have", "position": 2, "is_archived": false, "default_text": null } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecards/search": { "post": { "operationId": "searchScorecards", "summary": "Search scorecards", "description": "Search and filter scorecards (candidate evaluations) with pagination and sorting.\n\n**Filters**: `person_id`, `job_id`, `candidate_id`, `template_id`, `created_by_ids`, `is_starred`, `is_draft`.\n\n**Sorting**: `sort_by` — `created_at` (default), `updated_at`, or `overall_rating`. `sort_order` — `asc` or `desc` (default).\n\n**Pagination**: `offset` and `limit` (max 100).", "tags": [ "Scorecards" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardsSearchBody" } } } }, "responses": { "200": { "description": "Scorecards found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardsSearchResponse" }, "example": { "success": true, "data": [ { "id": "ddddeeee-1111-2222-3333-444444444444", "person_id": "123e4567-e89b-12d3-a456-426614174000", "job_id": "456e7890-e12b-34d5-a678-901234567890", "candidate_id": "eeeeffff-1111-2222-3333-444444444444", "assessment_template_id": "aaaa1111-2222-3333-4444-555555555555", "template": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "rating_scale": 5 }, "job": { "id": "456e7890-e12b-34d5-a678-901234567890", "title": "Senior Backend Engineer", "company_name": "Acme Inc." }, "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "overall_rating": 4.5, "overall_comment": "Strong systems-design depth and excellent async collaboration. Recommend moving forward.", "is_starred": true, "is_draft": false, "visible_in_client_share_link": false, "criterion_ratings": [ { "id": "cc11aa22-3333-4444-5555-666666666666", "criterion_id": "bbbb1111-2222-3333-4444-555555555555", "criterion_name": "System design depth", "importance": "must_have", "position": 1, "rating": 5, "comment": "Designed a multi-region payments service with clear failure-mode reasoning." }, { "id": "cc11aa22-3333-4444-5555-777777777777", "criterion_id": "cccc1111-2222-3333-4444-555555555555", "criterion_name": "Async collaboration", "importance": "nice_to_have", "position": 2, "rating": 4, "comment": "Strong written communication; decision log was thorough." } ], "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z" } ], "meta": { "total": 1, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecards/{id}": { "get": { "operationId": "getScorecardById", "summary": "Get scorecard by ID", "description": "Retrieve a single scorecard by its UUID, including criterion ratings (sorted by criterion position), embedded template, job, and creator.", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard ID" } } ], "responses": { "200": { "description": "Scorecard found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardByIdResponse" }, "example": { "success": true, "data": { "id": "ddddeeee-1111-2222-3333-444444444444", "person_id": "123e4567-e89b-12d3-a456-426614174000", "job_id": "456e7890-e12b-34d5-a678-901234567890", "candidate_id": "eeeeffff-1111-2222-3333-444444444444", "assessment_template_id": "aaaa1111-2222-3333-4444-555555555555", "template": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "rating_scale": 5 }, "job": { "id": "456e7890-e12b-34d5-a678-901234567890", "title": "Senior Backend Engineer", "company_name": "Acme Inc." }, "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "overall_rating": 4.5, "overall_comment": "Strong systems-design depth and excellent async collaboration. Recommend moving forward.", "is_starred": true, "is_draft": false, "visible_in_client_share_link": false, "criterion_ratings": [ { "id": "cc11aa22-3333-4444-5555-666666666666", "criterion_id": "bbbb1111-2222-3333-4444-555555555555", "criterion_name": "System design depth", "importance": "must_have", "position": 1, "rating": 5, "comment": "Designed a multi-region payments service with clear failure-mode reasoning." }, { "id": "cc11aa22-3333-4444-5555-777777777777", "criterion_id": "cccc1111-2222-3333-4444-555555555555", "criterion_name": "Async collaboration", "importance": "nice_to_have", "position": 2, "rating": 4, "comment": "Strong written communication; decision log was thorough." } ], "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateScorecard", "summary": "Update scorecard", "description": "Update an existing scorecard. Only provided fields are modified.\n\n**Criterion ratings**: when `criterion_ratings` is provided, all existing criterion ratings on this scorecard are replaced. Pass an empty array to clear them.\n\n**Team member assignment**: `last_updated_by` is the calling team member. Pass `team_member_id` only when authenticating with an API key.", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardUpdateRequest" } } } }, "responses": { "200": { "description": "Scorecard updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardUpdateResponse" }, "example": { "success": true, "data": { "id": "ddddeeee-1111-2222-3333-444444444444", "person_id": "123e4567-e89b-12d3-a456-426614174000", "job_id": "456e7890-e12b-34d5-a678-901234567890", "candidate_id": "eeeeffff-1111-2222-3333-444444444444", "assessment_template_id": "aaaa1111-2222-3333-4444-555555555555", "template": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "rating_scale": 5 }, "job": { "id": "456e7890-e12b-34d5-a678-901234567890", "title": "Senior Backend Engineer", "company_name": "Acme Inc." }, "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "overall_rating": 4.5, "overall_comment": "Strong systems-design depth and excellent async collaboration. Recommend moving forward.", "is_starred": true, "is_draft": false, "visible_in_client_share_link": false, "criterion_ratings": [ { "id": "cc11aa22-3333-4444-5555-666666666666", "criterion_id": "bbbb1111-2222-3333-4444-555555555555", "criterion_name": "System design depth", "importance": "must_have", "position": 1, "rating": 5, "comment": "Designed a multi-region payments service with clear failure-mode reasoning." }, { "id": "cc11aa22-3333-4444-5555-777777777777", "criterion_id": "cccc1111-2222-3333-4444-555555555555", "criterion_name": "Async collaboration", "importance": "nice_to_have", "position": 2, "rating": 4, "comment": "Strong written communication; decision log was thorough." } ], "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteScorecard", "summary": "Delete scorecard", "description": "Permanently deletes a scorecard and its criterion ratings.", "tags": [ "Scorecards" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Scorecard ID" } } ], "responses": { "200": { "description": "Scorecard deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Scorecard deleted successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/scorecards": { "post": { "operationId": "createScorecard", "summary": "Create scorecard", "description": "Create a new scorecard (candidate evaluation) for a person.\n\n**Job scoping**: pass `job_id` to attach the scorecard to a specific job. `candidate_id` is auto-resolved from the (person_id, job_id) candidate record.\n\n**Criterion ratings**: include `criterion_ratings` to score individual criteria from the template. Each entry must reference a `criterion_id` belonging to the template and include a `rating`, a `comment`, or both.\n\n**Team member assignment**: the scorecard is recorded as created by the calling team member. Pass `team_member_id` only when authenticating with an API key (no implicit member context). Session and OAuth callers cannot attribute creation to a different member.", "tags": [ "Scorecards" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardCreateRequest" } } } }, "responses": { "201": { "description": "Scorecard created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardCreateResponse" }, "example": { "success": true, "data": { "id": "ddddeeee-1111-2222-3333-444444444444", "person_id": "123e4567-e89b-12d3-a456-426614174000", "job_id": "456e7890-e12b-34d5-a678-901234567890", "candidate_id": "eeeeffff-1111-2222-3333-444444444444", "assessment_template_id": "aaaa1111-2222-3333-4444-555555555555", "template": { "id": "aaaa1111-2222-3333-4444-555555555555", "name": "Senior Backend Engineer Scorecard", "rating_scale": 5 }, "job": { "id": "456e7890-e12b-34d5-a678-901234567890", "title": "Senior Backend Engineer", "company_name": "Acme Inc." }, "created_by": { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" }, "overall_rating": 4.5, "overall_comment": "Strong systems-design depth and excellent async collaboration. Recommend moving forward.", "is_starred": true, "is_draft": false, "visible_in_client_share_link": false, "criterion_ratings": [ { "id": "cc11aa22-3333-4444-5555-666666666666", "criterion_id": "bbbb1111-2222-3333-4444-555555555555", "criterion_name": "System design depth", "importance": "must_have", "position": 1, "rating": 5, "comment": "Designed a multi-region payments service with clear failure-mode reasoning." }, { "id": "cc11aa22-3333-4444-5555-777777777777", "criterion_id": "cccc1111-2222-3333-4444-555555555555", "criterion_name": "Async collaboration", "importance": "nice_to_have", "position": 2, "rating": 4, "comment": "Strong written communication; decision log was thorough." } ], "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/tasks/search": { "post": { "operationId": "searchTasks", "summary": "Search tasks", "description": "Search and filter tasks with pagination and sorting.\n\n**Filters**: `keywords` (full-text search on task content), `task_types` (array of enum values), `related_to` + `related_record_type` (entity association), `is_completed` (boolean), `owner_ids` (assigned team members), `due_date_start` / `due_date_end` (date range — tasks with no due date are excluded).\n\n**Sorting**: `sort_by` — one of `created_at` (default), `updated_at`, `due_date`. `sort_order` — `asc` or `desc` (default).\n\n**Pagination**: `offset` and `limit` (max 100).", "tags": [ "Tasks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksSearchBody" } } } }, "responses": { "200": { "description": "Tasks found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksSearchResponse" }, "example": { "success": true, "data": [ { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "content_text": "Follow up with candidate about interview availability", "task_type": "text", "due_date": "2024-02-15T17:00:00Z", "is_completed": false, "person_id": "123e4567-e89b-12d3-a456-426614174000", "deal_id": "234e5678-e90a-12b3-c456-789012345678", "client_id": "345e6789-e01b-23c4-d567-890123456789", "job_id": "456e7890-e12b-34d5-a678-901234567890", "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-01T10:00:00Z", "owners": [ { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" } ] } ], "meta": { "total": 42, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/tasks/{id}": { "get": { "operationId": "getTaskById", "summary": "Get task by ID", "description": "Retrieve a single task by its UUID, including owner information.", "tags": [ "Tasks" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Task ID" } } ], "responses": { "200": { "description": "Task found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskByIdResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "content_text": "Follow up with candidate about interview availability", "task_type": "text", "due_date": "2024-02-15T17:00:00Z", "is_completed": false, "person_id": "123e4567-e89b-12d3-a456-426614174000", "deal_id": "234e5678-e90a-12b3-c456-789012345678", "client_id": "345e6789-e01b-23c4-d567-890123456789", "job_id": "456e7890-e12b-34d5-a678-901234567890", "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-01T10:00:00Z", "owners": [ { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "patch": { "operationId": "updateTask", "summary": "Update task", "description": "Update an existing task. Only provided fields are modified; omitted fields remain unchanged.", "tags": [ "Tasks" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Task ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateRequest" } } } }, "responses": { "200": { "description": "Task updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateResponse" }, "example": { "success": true, "data": { "message": "Task updated successfully" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "delete": { "operationId": "deleteTask", "summary": "Delete task", "description": "Permanently delete a task by its UUID. Deleting a task that blocks a sequence enrollment automatically advances that enrollment, equivalent to continuing the blocked sequence stage.", "tags": [ "Tasks" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Task ID" } } ], "responses": { "200": { "description": "Task deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on successful deletion." }, "message": { "type": "string", "description": "Deletion confirmation message." } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Task deleted successfully" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/tasks": { "post": { "operationId": "createTask", "summary": "Create task", "description": "Create a new task with required content and type. Optionally associate with a person, deal, client, or job. When `owner_ids` is omitted or empty, the authenticated team member is assigned; API-key requests without a team member create an ownerless task.", "tags": [ "Tasks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" } } } }, "responses": { "201": { "description": "Task created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateResponse" }, "example": { "success": true, "data": { "id": "aaa11111-bbbb-cccc-dddd-eeeeeeee1111", "content_text": "Follow up with candidate about interview availability", "task_type": "text", "due_date": "2024-02-15T17:00:00Z", "is_completed": false, "person_id": "123e4567-e89b-12d3-a456-426614174000", "deal_id": "234e5678-e90a-12b3-c456-789012345678", "client_id": "345e6789-e01b-23c4-d567-890123456789", "job_id": "456e7890-e12b-34d5-a678-901234567890", "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-01T10:00:00Z", "owners": [ { "id": "567e8901-e23c-45d6-e789-012345678901", "first_name": "Jane", "last_name": "Smith" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/team-capacity": { "get": { "operationId": "getTeamCapacityReport", "summary": "Get the Team Capacity report", "description": "Returns the Team Capacity board: one row per active team member with their active searches, stage breakdown, role breakdown, load score, workload tier, and quarter and year-to-date metrics.\n\nThe report applies the team’s saved board settings (job status filter, role filter, stage thresholds, role weights, workload thresholds, and sort), and returns those settings with it. Change them with `PATCH /v1/team-capacity/settings`.\n\nQuarter and year boundaries are calendar quarters and years in UTC.\n\nAPI keys need the `reports:read` scope.", "tags": [ "Team Capacity" ], "responses": { "200": { "description": "Team Capacity report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamCapacityReportResponse" }, "example": { "success": true, "data": { "generated_at": "2026-10-13T15:30:00.000Z", "quarter_start": "2026-10-01T00:00:00.000Z", "year_start": "2026-01-01T00:00:00.000Z", "is_configured": true, "settings": { "show_search_stage": true, "stage_config": { "stage_1_name": "New", "stage_1_max_weeks": 2, "stage_2_name": "Active", "stage_2_max_weeks": 4, "stage_3_name": "Ongoing" }, "show_load_score": true, "role_weights": [ { "role_name": "Lead Recruiter", "weight": 75 }, { "role_name": "Sourcer", "weight": 25 } ], "enable_active_search_color_coding": true, "active_search_color_thresholds": { "moderate_min": 5, "heavy_min": 8 }, "job_status_filter": [ "Active", "On Hold" ], "role_filter": [], "sort": { "column": "total_searches", "direction": "desc" } }, "summary": { "member_count": 2, "active_search_count": 6, "team_avg_load_score": 312.5 }, "available_roles": [ { "name": "Lead Recruiter", "is_owner_role": true }, { "name": "Sourcer", "is_owner_role": false } ], "available_job_statuses": [ { "name": "Active", "color": "#22c55e", "status_type": "in_progress" }, { "name": "On Hold", "color": "#f59e0b", "status_type": "in_progress" }, { "name": "Placed", "color": "#6366f1", "status_type": "closed_won" } ], "members": [ { "team_member_id": "234e5678-e90a-12b3-c456-789012345678", "first_name": "Jane", "last_name": "Smith", "title": "Partner", "image_url": "https://img.clerk.com/jane-smith.png", "total_searches": 5, "workload_tier": "moderate", "stage_breakdown": { "stage_1": 1, "stage_2": 2, "stage_3": 2 }, "role_breakdown": [ { "role_name": "Lead Recruiter", "active_searches": 4 }, { "role_name": "Sourcer", "active_searches": 2 } ], "load_score": 350, "kicked_off_this_quarter": 2, "closed_this_quarter": 1, "avg_days_out": 34.6, "avg_days_left": 41.2, "ytd_avg_fill_days": 96.5, "active_searches": [ { "job_id": "345e6789-e01b-23c4-d567-890123456789", "title": "Senior Software Engineer", "company_name": "Acme Corp", "company_domain": "acme.com", "open_date": "2026-10-06", "end_date": "2026-12-15", "role_names": [ "Lead Recruiter", "Sourcer" ] } ] }, { "team_member_id": "456e7890-e12b-34c5-d678-901234567890", "first_name": "Alex", "last_name": "Chen", "title": "Associate", "image_url": null, "total_searches": 1, "workload_tier": "light", "stage_breakdown": { "stage_1": 0, "stage_2": 0, "stage_3": 1 }, "role_breakdown": [ { "role_name": "Lead Recruiter", "active_searches": 1 } ], "load_score": 75, "kicked_off_this_quarter": 0, "closed_this_quarter": 0, "avg_days_out": 88, "avg_days_left": -3, "ytd_avg_fill_days": null, "active_searches": [ { "job_id": "567e8901-e23c-45d6-e789-012345678901", "title": "Chief Financial Officer", "company_name": "Globex", "company_domain": "globex.com", "open_date": "2026-07-17", "end_date": "2026-10-10", "role_names": [ "Lead Recruiter" ] } ] } ] } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/team-capacity/settings": { "patch": { "operationId": "updateTeamCapacitySettings", "summary": "Update Team Capacity settings", "description": "Updates the shared Team Capacity board settings for the whole team. Send only the settings you want to change: nested objects merge field by field, `role_weights` entries update one role each, and the filter arrays replace the current value.\n\nJob status and role names must match `available_job_statuses` and the team’s job team roles (see `available_roles` on `GET /v1/team-capacity`).\n\nReturns the saved settings. Roles without a saved weight are left out; `GET /v1/team-capacity` shows the default weight it applies to them.\n\nOnly organization admins can update these settings. API keys need the `reports:write` scope.", "tags": [ "Team Capacity" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamCapacitySettingsUpdate" } } } }, "responses": { "200": { "description": "Team Capacity settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamCapacitySettingsResponse" }, "example": { "success": true, "data": { "show_search_stage": true, "stage_config": { "stage_1_name": "New", "stage_1_max_weeks": 2, "stage_2_name": "Active", "stage_2_max_weeks": 4, "stage_3_name": "Ongoing" }, "show_load_score": true, "role_weights": [ { "role_name": "Lead Recruiter", "weight": 75 }, { "role_name": "Sourcer", "weight": 25 } ], "enable_active_search_color_coding": true, "active_search_color_thresholds": { "moderate_min": 5, "heavy_min": 8 }, "job_status_filter": [ "Active", "On Hold" ], "role_filter": [], "sort": { "column": "total_searches", "direction": "desc" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/team-members": { "get": { "operationId": "listTeamMembers", "summary": "List team members", "description": "Retrieve a paginated list of team members (recruiters and staff). Supports filtering by active status, first name, last name, and email address.\n\n**When to use**: Call this to discover team member IDs needed for filtering in search endpoints — e.g. `person_owner_ids_included`, `candidate_owner_ids_included`, `sourced_by_ids`, or `team_member_attribute_filters` in `POST /v1/persons/search`.", "tags": [ "Team Members" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Records to skip for pagination. Defaults to 0." }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Max records per page (1–100). Defaults to 100." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter by active status. true = active only, false = inactive only, omit = all." }, "required": false, "name": "is_active", "in": "query" }, { "schema": { "type": "string", "description": "Filter by first name (case-insensitive partial match)." }, "required": false, "name": "first_name", "in": "query" }, { "schema": { "type": "string", "description": "Filter by last name (case-insensitive partial match)." }, "required": false, "name": "last_name", "in": "query" }, { "schema": { "type": "string", "description": "Filter by email address (case-insensitive exact match against the team member's auth user email)." }, "required": false, "name": "email_address", "in": "query" } ], "responses": { "200": { "description": "Team members fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMembersListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "first_name": "Jane", "last_name": "Smith", "email": "jane@company.com", "image_url": null, "is_active": true } ], "meta": { "total": 8, "offset": 0, "limit": 100 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/team-members/{id}": { "get": { "operationId": "getTeamMemberById", "summary": "Get team member by ID", "description": "Retrieve a single team member by UUID. Useful for resolving team member IDs from webhook payloads (e.g. `sourced_by_team_member`, `last_stage_updated_by`, `owner_id`).", "tags": [ "Team Members" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "Team member UUID" } } ], "responses": { "200": { "description": "Team member fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberByIdResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "first_name": "Jane", "last_name": "Smith", "email": "jane@company.com", "image_url": null, "is_active": true } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/v1/webhooks/portal": { "get": { "operationId": "getWebhookPortal", "summary": "Get webhook management portal URL", "description": "Returns a Svix App Portal magic link URL for the current team. Embed in an iframe or open directly for endpoint management, delivery logs, and replay.\n\n**Requirements**: Webhooks must be available on the organization plan and enabled in organization settings. API-key callers also require the `webhooks:write` scope. Requests that do not meet these requirements return `403`.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Portal URL generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Svix App Portal magic link URL. Embed as iframe or open directly." } }, "required": [ "url" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "url": "https://app.svix.com/login#key=..." } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "Webhook portal access is unavailable or unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "example": { "success": false, "error": { "code": "INSUFFICIENT_SCOPE", "message": "API key does not have the required scope" } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. \"VALIDATION_ERROR\", \"NOT_FOUND\")." }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "object", "additionalProperties": {}, "description": "Extra facts about the error when they help you fix it, such as a limit and when it resets." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } } }, "webhooks": {}, "security": [ { "bearerAuth": [] } ] }