> ## 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. # List persons (deprecated) > **Deprecated** — Use `POST /v1/persons/search` instead for full filtering, sorting, and include control. Retrieve a paginated list of ALL persons with optional sorting — no filtering. **Pagination**: Use `offset` and `limit` query params (max 100 per page). **Sorting**: Set `sort_by` to one of: `name`, `created_at`, `updated_at`, `current_job_title`, `company`, `location`, `date_of_last_engagement`, `person_owner`, `last_activity_type`, `contact_email`, or `custom_` for custom fields. Use `sort_order` (`asc` or `desc`, default `desc`). **Include control**: The `include` query param accepts a comma-separated list of section names. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `related_people`, `offers`. When omitted, defaults to `work_experience, education_experience, certifications`. Pass an empty string to return only base fields. ## OpenAPI ````yaml /api-reference/openapi-v1.json get /v1/persons 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: get: tags: - Persons summary: List persons (deprecated) description: >- **Deprecated** — Use `POST /v1/persons/search` instead for full filtering, sorting, and include control. Retrieve a paginated list of ALL persons with optional sorting — no filtering. **Pagination**: Use `offset` and `limit` query params (max 100 per page). **Sorting**: Set `sort_by` to one of: `name`, `created_at`, `updated_at`, `current_job_title`, `company`, `location`, `date_of_last_engagement`, `person_owner`, `last_activity_type`, `contact_email`, or `custom_` for custom fields. Use `sort_order` (`asc` or `desc`, default `desc`). **Include control**: The `include` query param accepts a comma-separated list of section names. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `related_people`, `offers`. When omitted, defaults to `work_experience, education_experience, certifications`. Pass an empty string to return only base fields. operationId: listPersons parameters: - schema: type: - integer - 'null' minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. required: false name: offset in: query - schema: type: integer minimum: 1 maximum: 100 default: 100 description: Max records per page (1–100). Defaults to 100. required: false name: limit in: query - schema: type: string description: >- Sort column. Values: name, created_at, updated_at, current_job_title, company, location, date_of_last_engagement, person_owner, last_activity_type, contact_email, or custom_ for custom fields. Defaults to created_at. example: created_at required: false name: sort_by in: query - schema: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc (newest first). required: false name: sort_order in: query - schema: type: string description: >- Comma-separated sections to embed in each person. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, related_people, offers. Default: work_experience, education_experience, certifications. Pass empty string for base fields only (id, name, emails, phones, etc.). example: work_experience,candidates,custom_fields required: false name: include in: query responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PersonsSearchResponse' example: success: true data: - id: 123e4567-e89b-12d3-a456-426614174000 name: John Doe linkedin_public_id: johndoe first_name: John last_name: Doe current_job_title: Software Engineer current_company_name: Tech Corp current_company_id: 456e7890-e12b-34d5-a678-901234567890 external_source_id: null created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-06-20T14:45:00.000Z' image_url: https://media.samplecdn.com/dms/image/example.jpg location: San Francisco, CA latitude: 37.7749 longitude: -122.4194 date_of_last_engagement: '2024-06-18T09:00:00.000Z' last_activity_type: email do_not_contact: false do_not_contact_reason: null 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 deprecated: true components: schemas: 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". 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". 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". 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". 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. ````