> ## 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` (partial, case-insensitive), `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 & 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). **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, 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`. **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` (partial, case-insensitive), `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 & 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). **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, 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`. **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 emails: - contact_data_type: work value: john@techcorp.com phones: - contact_data_type: mobile value: +1-555-0123 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 - attribute_id: b2c3d4e5-f6a7-8901-bcde-f12345678901 attribute_name: Years of Experience data_type: number value: 8 tag: null team_member: null activities: - id: fff66666-0000-1111-2222-333333336666 activity_type: pipeline_status created_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 - id: 901e2345-e67f-89a0-b123-456789012345 activity_type: secondary_note created_at: '2024-01-14T16: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' 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 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' 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 total_estimated_compensation: 290000 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: Filter by name (partial, case-insensitive). 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: Full-text keyword search across profile data. 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). 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"). activity_types_excluded: type: array items: type: string description: Exclude persons with activities of these types. activity_content_keywords: type: array items: type: string description: Filter by keywords found in activity content text. 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. 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. 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. 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.). phones: type: array items: $ref: '#/components/schemas/PersonContactValue' description: All phone numbers on file, each with a type (mobile, work, etc.). 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 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. 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 - 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 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. required: - attribute_id - attribute_name - data_type - job_id - list_id - value - tag - team_member 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. Synthetic: task, calendar_event, sequence_enrollment, pipeline_status, assessment. created_at: type: string description: ISO 8601 timestamp. 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". 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. required: - stage_name - is_rejection_stage - entered_at - exited_at - reason_text 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 - 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 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 - 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' required: - id - name - color 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. 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 - 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. ````