> ## 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. # Set preferred email > Star a stored email as this person's preferred address and return the updated person. Campaign enrollment uses the preferred email when it is set. The email must already exist on the person. To update many people in one request, use `POST /v1/persons/preferred-email`. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/{id}/preferred-email 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/{id}/preferred-email: post: tags: - Persons summary: Set preferred email description: >- Star a stored email as this person's preferred address and return the updated person. Campaign enrollment uses the preferred email when it is set. The email must already exist on the person. To update many people in one request, use `POST /v1/persons/preferred-email`. operationId: setPersonPreferredEmail parameters: - in: path name: id required: true schema: type: string description: Person UUID requestBody: content: application/json: schema: $ref: '#/components/schemas/SetPreferredEmailRequest' responses: '200': description: Preferred email set content: application/json: schema: $ref: '#/components/schemas/PersonByIdResponse' example: success: true data: id: 123e4567-e89b-12d3-a456-426614174000 name: John Doe linkedin_public_id: johndoe first_name: John last_name: Doe current_job_title: Software Engineer current_company_name: Tech Corp current_company_id: 456e7890-e12b-34d5-a678-901234567890 external_source_id: null created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-06-20T14:45:00.000Z' image_url: https://media.samplecdn.com/dms/image/example.jpg location: San Francisco, CA latitude: 37.7749 longitude: -122.4194 date_of_last_engagement: '2024-06-18T09:00:00.000Z' last_activity_type: email do_not_contact: false do_not_contact_reason: null 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' 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' 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 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' '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: SetPreferredEmailRequest: type: object properties: email: type: string minLength: 1 description: >- Email address to star as preferred. Must already exist on this person. required: - email PersonByIdResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/PersonDetails' required: - success - data PersonDetails: type: object properties: id: type: string description: Unique person UUID. Use as path param in GET /v1/persons/{id}. name: type: - string - 'null' description: Full name (first + last). linkedin_public_id: type: - string - 'null' description: LinkedIn vanity slug (e.g. "johndoe" from linkedin.com/in/johndoe). first_name: type: - string - 'null' description: First name. last_name: type: - string - 'null' description: Last name. current_job_title: type: - string - 'null' description: Current job title from their profile. current_company_name: type: - string - 'null' description: Current employer name. current_company_id: type: - string - 'null' description: >- UUID of the current employer company. Matches IDs from GET /v1/companies. external_source_id: type: - string - 'null' description: >- Identifier from an external system (e.g. HRIS or legacy ATS import ID). created_at: type: - string - 'null' description: ISO 8601 timestamp when the person record was created. updated_at: type: - string - 'null' description: ISO 8601 timestamp when the person record was last updated. image_url: type: - string - 'null' description: Profile photo URL. location: type: - string - 'null' description: Location string from the profile (e.g. "San Francisco, CA"). latitude: type: - number - 'null' description: Geographic latitude derived from location, for proximity filtering. longitude: type: - number - 'null' description: Geographic longitude derived from location, for proximity filtering. date_of_last_engagement: type: - string - 'null' description: >- ISO 8601 timestamp of the most recent activity or communication with this person. last_activity_type: type: - string - 'null' description: >- Type key of the most recent activity (e.g. "email", "primary_note", "linkedin_message"). do_not_contact: type: boolean description: When true, this person has been marked as do-not-contact. do_not_contact_reason: type: - string - 'null' description: Free-text reason for the do-not-contact flag, if provided. 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. 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. ````