> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Advanced person search > 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. **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). **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). **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`. **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. **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`). **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`, `related_people`, `offers`. 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. **API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, and `compensation` and `offers` require `compensation: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. **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.). ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/search 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 security: - bearerAuth: [] 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. paths: /v1/persons/search: post: tags: - Persons 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. **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). **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). **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`. **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. **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`). **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`, `related_people`, `offers`. 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. **API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, and `compensation` and `offers` require `compensation: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. **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.). operationId: searchPersons 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 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 - contact_data_type: personal value: john@gmail.com is_preferred: 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 note: Worked together on Platform team direction: outgoing 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' 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. 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. 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. required: - code - message required: - success - error components: schemas: 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 - related_people - offers description: >- Sections to embed in each person record. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, related_people, offers. 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, and compensation and offers require compensation: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. 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. 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. 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/PersonContactValue' description: >- All email addresses on file, each with a type (work, personal, etc.) and whether it is preferred. 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. related_people: type: array items: $ref: '#/components/schemas/RelatedPerson' description: Related persons. 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. 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 - owner_id - emails - phones - preferred_email - preferred_phone 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 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 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. 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". 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"). note: type: - string - 'null' description: Free-text note about the relation. direction: type: string enum: - outgoing - incoming description: >- "outgoing" if this person created the relation, "incoming" if the other person did. 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 - note - direction - 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.