# Generate an activity & stage-change report Source: https://docs.stardex.com/api-reference/activity-reports/generate-an-activity-&-stage-change-report /api-reference/openapi-v1.json post /v1/activity-reports Aggregates recruiter activity, candidate sourcing, pipeline stage changes, campaign enrollments, and tasks for the requested date window. Group by recruiter, job, or company. Mirrors the in-app "Generate report" surface and is the recommended way to produce daily / weekly / monthly performance reports. Session and OAuth callers need `org:reports:candidate_pipeline` (`org:admin` bypasses). `crm_activities` also needs `org:reports:crm`; without it that include is dropped. API keys are gated by `reports:read`. **Date filter**: applies to `created_at` for activities / candidates / tasks, `entered_at` for stage changes, and `enrolled_at` for campaign enrollments. **Optional sections** via `include`: - `pipeline_snapshot` — current candidate count per pipeline stage (job/company segments only). - `job_breakdown` — per-job candidates-sourced breakdown for each recruiter (team_member segments only). - `crm_activities` — fold `client_activities` + `client_status_changes` into the company segment metrics. # Archive automation Source: https://docs.stardex.com/api-reference/automations/archive-automation /api-reference/openapi-v1.json delete /v1/automations/{id} Archives the automation and disables new fires. The recipe stays recoverable via `PATCH` with `is_archived: false`. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta. # Create automation Source: https://docs.stardex.com/api-reference/automations/create-automation /api-reference/openapi-v1.json post /v1/automations Create an automation with exactly one trigger and one or more actions. `add_note` and `send_email` to a candidate are only valid when `trigger.type` is `candidate_status_changed`. Schedule `next_run_at` is computed from `rrule`, `dtstart`, and `timezone`. API keys can't create an automation that emails a candidate or client contacts from a mailbox (`payload.sender`), because it would send as a team member; set those up in the app. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta. # Get automation by ID Source: https://docs.stardex.com/api-reference/automations/get-automation-by-id /api-reference/openapi-v1.json get /v1/automations/{id} Retrieve one automation, including its trigger and ordered actions. Archived automations are still returned by ID. # Get automation run by ID Source: https://docs.stardex.com/api-reference/automations/get-automation-run-by-id /api-reference/openapi-v1.json get /v1/automations/runs/{runId} Retrieve one run and its per-action steps. Only organization admins, API keys and the automation's creator can see its runs. # List automation action types Source: https://docs.stardex.com/api-reference/automations/list-automation-action-types /api-reference/openapi-v1.json get /v1/automations/action-types Returns the closed set of action types you can attach to an automation. # List automation run statuses Source: https://docs.stardex.com/api-reference/automations/list-automation-run-statuses /api-reference/openapi-v1.json get /v1/automations/run-statuses Returns the closed set of statuses a run can be in. # List automation trigger types Source: https://docs.stardex.com/api-reference/automations/list-automation-trigger-types /api-reference/openapi-v1.json get /v1/automations/trigger-types Returns the closed set of trigger types you can save on an automation. # Search automation runs Source: https://docs.stardex.com/api-reference/automations/search-automation-runs /api-reference/openapi-v1.json post /v1/automations/{id}/runs/search Paginated run log for one automation. Does not include per-action steps; use `GET /v1/automations/runs/{runId}` for steps. Only organization admins, API keys and the automation's creator can see its runs. # Search automations Source: https://docs.stardex.com/api-reference/automations/search-automations /api-reference/openapi-v1.json post /v1/automations/search Search saved automations with pagination and sorting. **Filters**: `keywords` (name substring), `is_enabled`, `is_archived` (defaults to false), `trigger_type`. **Sorting**: `sort_by` — `created_at` (default), `updated_at`, `name`. `sort_order` — `asc` or `desc` (default). List rows include action counts, not the full trigger or action payloads. Use `GET /v1/automations/{id}` for the full recipe. # Update automation Source: https://docs.stardex.com/api-reference/automations/update-automation /api-reference/openapi-v1.json patch /v1/automations/{id} Partially update an automation. `is_enabled` toggles new fires; already-claimed runs still finish. When `trigger` is sent, the schedule or status row is replaced. When `actions` is sent, the full action list is replaced. An automation that emails candidates or client contacts from a mailbox can only be edited by its creator; other admins can still turn it off or archive it. Only organization admins (or an API key) can create, change, turn off or archive automations during the Beta. # Get calendar meeting by ID Source: https://docs.stardex.com/api-reference/calendar-meetings/get-calendar-meeting-by-id /api-reference/openapi-v1.json get /v1/calendar-meetings/{id} Retrieve detailed information about a specific calendar meeting including all associated recordings and their processing status. # List calendar meetings Source: https://docs.stardex.com/api-reference/calendar-meetings/list-calendar-meetings /api-reference/openapi-v1.json get /v1/calendar-meetings Retrieve a paginated list of calendar meetings tracked by the notetaker. **Filters**: `start_time_after` / `start_time_before` (ISO 8601 date range), `bot_status` (e.g. completed, failed, recording), `meeting_title` (case-insensitive text search). **Sorting**: `sort_by` (start_time, created_at) with `sort_order` (asc/desc, default desc). **Pagination**: Use `offset` and `limit` query params (max 100 per page). # Get candidate by ID Source: https://docs.stardex.com/api-reference/candidates/get-candidate-by-id /api-reference/openapi-v1.json get /v1/candidates/{id} Retrieve detailed information about a single candidate including their full pipeline stage history (all stages they have been through with dates). **When to use**: Use this when you need the stage history timeline for one specific candidate. For querying multiple candidates with filtering, use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead. # List rejection reasons Source: https://docs.stardex.com/api-reference/candidates/list-rejection-reasons /api-reference/openapi-v1.json get /v1/candidates/rejection-reasons Retrieve active rejection reasons configured for the requesting team. Use a returned `id` as `rejection_reason_id` when moving a candidate to a rejection stage with `POST /v1/candidates/update-stage`. # Remove candidate from job Source: https://docs.stardex.com/api-reference/candidates/remove-candidate-from-job /api-reference/openapi-v1.json delete /v1/candidates/{id} Remove a candidate from a job pipeline (soft archive). **Important**: This only removes the candidacy — the association between the person and the job. The **person record remains in the database** and is not deleted. Stage history and other job-linked candidacy data stay retained on the archived candidate row. To add the person back to a job later, use `POST /v1/persons` or `PATCH /v1/persons/{id}` with `job_id` (or the matching MCP tools). Get candidate IDs from `POST /v1/persons/search` with `include: ["candidates"]` or from `GET /v1/candidates/{id}`. Requires the `candidates:delete` API key scope. # Update candidate stage Source: https://docs.stardex.com/api-reference/candidates/update-candidate-stage /api-reference/openapi-v1.json post /v1/candidates/update-stage Moves a candidate to a different pipeline stage within a job. **Flexible identification**: Accepts job identification by `job_id` or `job_name`, candidate identification by `candidate_id`, `candidate_email`, or `candidate_name`, and stage identification by `stage_id` or `stage_name`. **Job resolution**: The endpoint resolves the job in this order: `job_id`, the job associated with `candidate_id`, `job_name`, then the person's most recent active candidacy created within the previous 180 days. When `candidate_id` is provided, its associated job takes precedence over `job_name`. **Discovering stage IDs/names**: Use `GET /v1/jobs/{id}` to see the full `pipeline_stages` array with stage IDs, names, and ordering for a specific job. **Rejection details**: When moving to a stage where `is_rejection_stage` is true, optionally pass `rejection_reason_id` from `GET /v1/candidates/rejection-reasons` and `reason_text` for additional context. Rejection details are not allowed for non-rejection stages. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident. # Create client contact Source: https://docs.stardex.com/api-reference/client-contacts/create-client-contact /api-reference/openapi-v1.json post /v1/client-contacts Promote an existing person into a client contact by linking them to a client company. The associated company is automatically flagged as a client. **Idempotency**: A person can be an active client contact for at most one client company per team (DB constraint). If a non-deleted client contact already exists for this person, the existing record is returned with `is_new: false` and the echoed `client_id` reflects the contact's actual client company — compare it to the requested `client_id` to detect mismatches. New contacts return 201 with `is_new: true`; existing contacts return 200. **Status**: When `client_contact_status_id` is omitted, the team default status is assigned. Pass null to leave the new contact without a status. **Owners**: When `owner_ids` is omitted, the authenticated caller is auto-assigned (if they are a team member). Pass an empty array to create a contact with no owners. # List client contact statuses Source: https://docs.stardex.com/api-reference/client-contacts/list-client-contact-statuses /api-reference/openapi-v1.json get /v1/client-contacts/statuses Returns all client contact statuses for the organization, ordered by stage_order. No pagination — the full list is always returned. **When to use**: Call this to discover available status IDs for `client_contact_status_id` when updating client contacts via PATCH /v1/client-contacts/:id. # Update client contact status Source: https://docs.stardex.com/api-reference/client-contacts/update-client-contact-status /api-reference/openapi-v1.json patch /v1/client-contacts/{id} Update a client contact's status. Pass a valid status UUID to change the status, or null to clear it. **ID**: Accepts a client contact UUID or a person UUID — if a person UUID is provided, the associated client contact is resolved automatically. **Status IDs**: Use GET /v1/client-contacts/statuses to discover available status IDs. # Create or update company Source: https://docs.stardex.com/api-reference/companies/create-or-update-company /api-reference/openapi-v1.json post /v1/companies Create a new company record or update an existing one. Matching is done by LinkedIn URL, domain, or name. At least one of name, domain, or linkedin_url must be provided. **Custom fields**: Pass `custom_fields` to set custom attribute values. Get attribute definitions from GET /v1/custom-fields/companies. # Get company by ID Source: https://docs.stardex.com/api-reference/companies/get-company-by-id /api-reference/openapi-v1.json get /v1/companies/{id} Retrieve detailed information about a specific company including client status, owners, enriched data, and custom field values. Custom fields are included by default; pass `include=` (empty) for base fields only. # Get company documents Source: https://docs.stardex.com/api-reference/companies/get-company-documents /api-reference/openapi-v1.json get /v1/companies/{id}/documents Retrieve a paginated list of documents attached to a company, including pitch decks, client information, fee agreements, and legal documents. Stored files receive short-lived signed download URLs; re-fetch when a URL expires. Pass include_text=true to receive extracted plain-text content when it is available. # List company client statuses Source: https://docs.stardex.com/api-reference/companies/list-company-client-statuses /api-reference/openapi-v1.json get /v1/companies/statuses Returns all company client statuses for the organization, ordered by stage_order. No pagination — the full list is always returned. **When to use**: Call this to discover available status IDs for `company_status_ids_included` / `company_status_ids_excluded` filters in `POST /v1/companies/search`, or for `client_status_id` when updating companies. # List company document types Source: https://docs.stardex.com/api-reference/companies/list-company-document-types /api-reference/openapi-v1.json get /v1/companies/document-types Returns every active company document type for the organization, ordered by name. No pagination — the full list is always returned. Document types are configurable per organization, so the available keys differ between organizations. Call this to discover valid `document_types` values for `GET /v1/companies/{id}/documents` and valid `type` values when uploading a document. # Search companies Source: https://docs.stardex.com/api-reference/companies/search-companies /api-reference/openapi-v1.json post /v1/companies/search Advanced company search with filtering, sorting, and custom attribute filters. **Filters**: keywords (name/domain/LinkedIn), exact domain, exact linkedin_url, is_client, company_status_ids_included/excluded, owner_ids_included/excluded, relationships_included/excluded, list_ids_included/excluded, job_id, company_ids. **Custom attribute filters**: `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters`. Get attribute IDs and tag IDs from GET /v1/custom-fields/companies. **Sorting**: Pass `sort_by` with one of: `name`, `domain`, `status` (client status stage order), `date_of_last_engagement`, `created_at` (default), or `custom_` for any custom field. Pair with `sort_order` (`asc` or `desc`, default `desc`). **Include control**: Pass `include: ["custom_fields"]` to embed custom field values in each result. # Update company Source: https://docs.stardex.com/api-reference/companies/update-company /api-reference/openapi-v1.json patch /v1/companies/{id} Update an existing company's information including name, domain, description, custom field values, and do-not-contact status. Only provided fields are updated; omitted fields remain unchanged. **Do-not-contact**: Pass `do_not_contact: true` to flag the company (blocks outreach to anyone whose current company is this one) or `false` to clear it. Optionally include a `do_not_contact_reason` (free text) and `do_not_contact_expiration_date` (ISO 8601 timestamp). When the expiration field is omitted on a new do-not-contact flag, the team default from `auth_organization_settings.auto_dnc_company_on_search_days` is applied (days-from-now); pass `null` explicitly for an indefinite do-not-contact. # Upload company document Source: https://docs.stardex.com/api-reference/companies/upload-company-document /api-reference/openapi-v1.json post /v1/companies/{id}/documents Upload a document for a company. Supports two modes: **1. Direct file upload** (`Content-Type: multipart/form-data`): Send the file in a `file` field with `title` and `type` metadata fields. Allowed file types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB. **2. JSON body** (`Content-Type: application/json`): Provide a `file_url` — a publicly accessible HTTPS URL. The server downloads the file, validates it, and stores it. # Create company activity (note) Source: https://docs.stardex.com/api-reference/company-activities/create-company-activity-note /api-reference/openapi-v1.json post /v1/company-activities Log a new activity (note, call note, meeting note, email, etc.) on a company record. The activity_type must be a key registered for the team — discover valid keys with `GET /v1/company-activities/types`. # Get company activity by ID Source: https://docs.stardex.com/api-reference/company-activities/get-company-activity-by-id /api-reference/openapi-v1.json get /v1/company-activities/{id} Retrieve a single company activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member. # List company activities Source: https://docs.stardex.com/api-reference/company-activities/list-company-activities /api-reference/openapi-v1.json get /v1/company-activities Returns a paginated list of activities (notes) attached to a company. Filtered by `organization_company_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys from GET /v1/company-activities/types). Sorted by `created_at` descending. # List company activity types Source: https://docs.stardex.com/api-reference/company-activities/list-company-activity-types /api-reference/openapi-v1.json get /v1/company-activities/types Returns every activity type registered for the requesting team — built-in types (e.g. `secondary_note`, `call_note`, `meeting_note`, `email`) and any custom types defined under Settings → Activity Types. No pagination — the full list is returned in a single response. **When to use**: Call this before creating a company activity, or before filtering `GET /v1/company-activities` by `activity_types` / `excluded_activity_types`, so you know which keys are valid for the team. # Update company activity (note) by ID Source: https://docs.stardex.com/api-reference/company-activities/update-company-activity-note-by-id /api-reference/openapi-v1.json patch /v1/company-activities/{id} Update the content of an existing company activity. Set `content_type` to `"text"` for plain text (auto-converted to HTML) or `"html"` for raw HTML input. # Dismiss multiple insights at once Source: https://docs.stardex.com/api-reference/company-insights/dismiss-multiple-insights-at-once /api-reference/openapi-v1.json post /v1/company-insights/bulk-dismiss Marks all provided insight IDs as `dismissed`. Already-dismissed ones are ignored. # Edit content or dismiss/restore an insight Source: https://docs.stardex.com/api-reference/company-insights/edit-content-or-dismissrestore-an-insight /api-reference/openapi-v1.json patch /v1/company-insights/{id} Update the fact text (sets `is_user_edited=true`) and/or set its status to `dismissed` (hides from search context and the UI) or `active`. # List AI-extracted insights for a company Source: https://docs.stardex.com/api-reference/company-insights/list-ai-extracted-insights-for-a-company /api-reference/openapi-v1.json get /v1/company-insights Returns AI-extracted, dismissable facts about a company that were derived from candidate notes and meeting transcripts. **Filters**: `organization_company_id` (required), `status` (default `active`), `category`. **Pagination**: `offset` and `limit` (max 100). Sorted by `observation_date` desc, then `created_at` desc. # Manually extract insights from an activity Source: https://docs.stardex.com/api-reference/company-insights/manually-extract-insights-from-an-activity /api-reference/openapi-v1.json post /v1/company-insights/trigger Runs the AI extraction pipeline on a specific activity (e.g. a secondary note or meeting transcript). Useful for re-running extraction or bypassing the cron. **Successful no-ops**: This endpoint returns `200` with `added_count: 0` when the activity is ineligible, the organization plan is not eligible, no linked companies or company-specific facts are found, or all extracted facts are duplicates. Some no-op responses have `ai_auto_update_id: null`; others reference an audit row marked as skipped. # Get company custom field definitions Source: https://docs.stardex.com/api-reference/custom-fields/get-company-custom-field-definitions /api-reference/openapi-v1.json get /v1/custom-fields/companies Retrieve custom attribute definitions for companies, including available tag options. **Scope**: By default, returns only global (company-level) definitions. Pass `job_id` to also include job-specific definitions for that job. Pass `list_id` to also include list-specific definitions. Optionally filter by `is_client` status. Both `job_id` and `list_id` can be combined. **When to use**: Call this to discover company-level attribute IDs and tag option IDs before using `current_company_attribute_filters` in person search endpoints. **Response**: Each definition includes `job_id` and `list_id` fields. Global attributes have both as null. Job-specific attributes have `job_id` set. List-specific attributes have `list_id` set. # Get deal custom field definitions Source: https://docs.stardex.com/api-reference/custom-fields/get-deal-custom-field-definitions /api-reference/openapi-v1.json get /v1/custom-fields/deals Retrieve custom attribute definitions for deals, including available tag options. **When to use**: Call this to discover deal-level attribute IDs needed for `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, or `team_member_attribute_filters` / `company_attribute_filters` in `POST /v1/deals/search`, or when setting `custom_fields` on deal create/update. # Get job custom field definitions Source: https://docs.stardex.com/api-reference/custom-fields/get-job-custom-field-definitions /api-reference/openapi-v1.json get /v1/custom-fields/jobs Retrieve custom attribute definitions for jobs, including available tag options. **When to use**: Call this to discover job-level attribute IDs needed when including `custom_fields` in job list/detail endpoints or sorting by `custom_` in search results. # Get person custom field definitions Source: https://docs.stardex.com/api-reference/custom-fields/get-person-custom-field-definitions /api-reference/openapi-v1.json get /v1/custom-fields/persons Retrieve custom attribute definitions for persons, including available tag options for select-type fields. **Scope**: By default, returns only global (person-level) definitions. Pass `job_id` to also include job-specific definitions for that job. Pass `list_id` to also include list-specific definitions. Both can be combined. **When to use**: Call this BEFORE using `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, or `team_member_attribute_filters` / `company_attribute_filters` in search endpoints (`POST /v1/persons/search`). You need the `attribute_id` and tag option IDs from this endpoint to construct those filters. **Example workflow**: To find persons tagged "banking" on a specific job → call this endpoint with `job_id` → find the "Tags" attribute → get its `id` as `attribute_id` → find the "banking" tag → get its `id` → pass both to `select_attribute_filters`. **Response**: Each definition includes `job_id` and `list_id` fields. Global attributes have both as null. Job-specific attributes have `job_id` set. List-specific attributes have `list_id` set. # Create deal activity (note) Source: https://docs.stardex.com/api-reference/deal-activities/create-deal-activity-note /api-reference/openapi-v1.json post /v1/deal-activities Log a new activity (note, call note, meeting note, email, etc.) on a deal record. Standard activity_type keys: `secondary_note`, `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for deals. # Get deal activity by ID Source: https://docs.stardex.com/api-reference/deal-activities/get-deal-activity-by-id /api-reference/openapi-v1.json get /v1/deal-activities/{id} Retrieve a single deal activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member. # List deal activities Source: https://docs.stardex.com/api-reference/deal-activities/list-deal-activities /api-reference/openapi-v1.json get /v1/deal-activities Returns a paginated list of activities (notes) attached to a deal. Filtered by `deal_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys). Sorted by `created_at` descending. # Update deal activity (note) by ID Source: https://docs.stardex.com/api-reference/deal-activities/update-deal-activity-note-by-id /api-reference/openapi-v1.json patch /v1/deal-activities/{id} Update the content of an existing deal activity. Set `content_type` to `"text"` for plain text (auto-converted to HTML) or `"html"` for raw HTML input. # Archive deal Source: https://docs.stardex.com/api-reference/deals/archive-deal /api-reference/openapi-v1.json delete /v1/deals/{id} Archive a deal by marking it as deleted. The record is retained and can be found with the `show_archived` search filter, fetched by ID, or unarchived with `PATCH /v1/deals/{id}` (`is_archived: false`). # Create deal Source: https://docs.stardex.com/api-reference/deals/create-deal /api-reference/openapi-v1.json post /v1/deals Create a new deal record. Provide `client_linkedin_url` to automatically look up or create the client company when `client_id` is not known. For API-key callers, `compensation` and `compensation_currency_code` on the response require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`. # Get deal by ID Source: https://docs.stardex.com/api-reference/deals/get-deal-by-id /api-reference/openapi-v1.json get /v1/deals/{id} Retrieve a single deal by UUID, including won/lost reasons and notes, with optional custom field values. Archived deals are returned the same as active ones. Check `is_archived` on the response. `client_contacts` are always included (empty array when none are linked). **Include**: By default, `custom_fields` are included. Pass `include=` (empty) for base fields only. For API-key callers, `compensation` and `compensation_currency_code` require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`. # List deal statuses Source: https://docs.stardex.com/api-reference/deals/list-deal-statuses /api-reference/openapi-v1.json get /v1/deals/statuses Returns all deal statuses for the organization, ordered by stage_order. No pagination — the full list is always returned. **When to use**: Call this to discover available status IDs for `deal_status_ids_included` / `deal_status_ids_excluded` filters in `POST /v1/deals/search`, or for `deal_status_id` when creating/updating deals. # Search deals Source: https://docs.stardex.com/api-reference/deals/search-deals /api-reference/openapi-v1.json post /v1/deals/search Search and filter deals with pagination and sorting using the deals_list_query RPC. **Filters**: `keywords` (name + company search), `deal_status_ids_included`/`excluded`, `owner_ids_included`/`excluded`, `show_open_deals_only`, `show_archived`, `closed_date_filter`, `open_date_filter`, and custom attribute filters (`select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters`). **Sorting**: `name`, `amount`, `win_probability`, `company`, `status`, `closed_date`, `open_date`, `last_contacted_at`, `created_at`, or `custom_` for custom attribute sorting. **Include**: Pass `["custom_fields"]` and/or `["client_contacts"]` to embed those sections. `client_contacts` are omitted unless explicitly requested. For API-key callers, `compensation` and `compensation_currency_code` require `compensation:read`; inaccessible fields are omitted. Deal `amount` and `pricing_rate` are available with `deals:read`. # Update deal Source: https://docs.stardex.com/api-reference/deals/update-deal /api-reference/openapi-v1.json patch /v1/deals/{id} Update an existing deal, including won/lost reason IDs and notes. Only provided fields are modified; omitted fields remain unchanged. Archived deals can be updated. Pass `is_archived: false` to unarchive, or `is_archived: true` to archive. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident. # Introduction Source: https://docs.stardex.com/api-reference/introduction-v1 Get started with the Stardex API ## Base URL All API requests should be made to: ```bash theme={null} https://api.stardex.ai ``` For example, to access the `/v1/persons` endpoint, you would make a request to: ```bash theme={null} https://api.stardex.ai/v1/persons ``` ## Authentication All API endpoints require authentication using Bearer tokens in the Authorization header. Add your API key as follows: ```bash theme={null} Authorization: Bearer your_api_key_here ``` You can get your API key from the [Stardex Settings](https://stardex.ai/settings/integrations). ## Response Format All API endpoints follow a consistent response format: ### Successful Responses ```json theme={null} { "success": true, "data": object // Response data } ``` For paginated responses: ```json theme={null} { "success": true, "data": array, "meta": { "total": number, "offset": number, "limit": number } } ``` ### Example Successful Response ```json theme={null} { "success": true, "data": { "id": "123", "name": "John Doe" // ... other fields } } ``` ### Error Responses ```json theme={null} { "success": false, "error": { "code": string, "message": string, } } ``` ### Example Error Response ```json theme={null} { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The provided API key is invalid or expired" } } ``` Common HTTP Status Codes: * `200`: Operation completed successfully * `400`: Invalid request or missing fields * `401`: Missing or invalid API key * `403`: Forbidden - insufficient permissions * `404`: Resource not found * `429`: Rate limit exceeded * `500`: Unexpected server error ## Rate Limits API requests are rate-limited using a **sliding window** of **60 requests per minute** per API key. If you exceed the limit, the API will respond with a `429 Too Many Requests` status code. Rate limits apply per API key. Each key has its own independent counter. ### Rate Limit Headers Every API response includes headers to help you track your current usage: | Header | Description | | - | - | | `X-RateLimit-Limit` | Maximum number of requests allowed per minute | | `X-RateLimit-Remaining` | Number of requests remaining in the current window | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the current window resets | ### Rate Limit Exceeded Response When the rate limit is exceeded, the API returns a `429` status code with a `Retry-After` header: ```json theme={null} { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Try again in 30 seconds.", "retry_after_seconds": 30, "limit": 60, "reset_at": 1717027200 } } ``` | Field | Description | | - | - | | `retry_after_seconds` | Seconds to wait before making another request | | `limit` | Your rate limit (requests per minute) | | `reset_at` | Unix timestamp (seconds) when the window resets | ### Best Practices * **Check rate limit headers** on every response to monitor your usage. * **Implement exponential backoff** when you receive a `429` response — wait for the `retry_after_seconds` value before retrying. * **Spread requests over time** rather than sending them in bursts to avoid hitting the limit. * **Cache responses** where possible to reduce the total number of API calls. # Create job activity (note) Source: https://docs.stardex.com/api-reference/job-activities/create-job-activity-note /api-reference/openapi-v1.json post /v1/job-activities Log a new activity (note, call note, meeting note, email, etc.) on a job record. Standard activity_type keys: `secondary_note`, `call_note`, `meeting_note`, `email`, `linkedin_message`, `text_message`. Free-form strings are accepted — there is no team-level type registry for jobs. # Get job activity by ID Source: https://docs.stardex.com/api-reference/job-activities/get-job-activity-by-id /api-reference/openapi-v1.json get /v1/job-activities/{id} Retrieve a single job activity by its UUID. Returns content in both HTML and plain-text formats plus the creator team member. # List job activities Source: https://docs.stardex.com/api-reference/job-activities/list-job-activities /api-reference/openapi-v1.json get /v1/job-activities Returns a paginated list of activities (notes) attached to a job. Filtered by `job_id` (required). Optionally filter by `activity_types` / `excluded_activity_types` (comma-separated keys). Sorted by `created_at` descending. # Update job activity (note) by ID Source: https://docs.stardex.com/api-reference/job-activities/update-job-activity-note-by-id /api-reference/openapi-v1.json patch /v1/job-activities/{id} Update the content of an existing job activity. Set `content_type` to `"text"` for plain text (auto-converted to HTML) or `"html"` for raw HTML input. # List job offer statuses Source: https://docs.stardex.com/api-reference/job-offers/list-job-offer-statuses /api-reference/openapi-v1.json get /v1/job-offers/statuses Returns all job offer statuses for the organization, ordered by stage_order. No pagination — the full list is always returned. **When to use**: Call this to discover status IDs for the `job_offer_status_id` filter in `GET /v1/job-offers`. **Access**: Session and OAuth callers need `org:reports:offer_tracking` (`org:admin` bypasses). API keys need the `offers:read` scope. # List job offers Source: https://docs.stardex.com/api-reference/job-offers/list-job-offers /api-reference/openapi-v1.json get /v1/job-offers Retrieve a paginated list of offers extended to candidates, with the job, client company, person, status, key dates, offer compensation, owners (team members credited on the offer), and client contacts attached to the offer. **Filters**: `job_id`, `candidate_id`, `person_id`, `job_offer_status_id`, `status_type` (pending, accepted, rejected, rescinded), and `extended_date_after` / `extended_date_before` (ISO 8601 date range). **Sorting**: `sort_by` (created_at, updated_at, extended_date, accepted_date, candidate_start_date) with `sort_order` (asc/desc, default desc). **Pagination**: Use `offset` and `limit` query params (max 100 per page). **Access**: Session and OAuth callers need `org:reports:offer_tracking` (`org:admin` bypasses). API keys need the `offers:read` scope. Compensation fields (`compensation_*`, `bonus_type`, equity grants, `relocation_bonus`, `sign_on_bonus`, `total_estimated_compensation`) are omitted for API keys without `compensation:read`. Offers on jobs the caller cannot access are not returned. # Add job target companies Source: https://docs.stardex.com/api-reference/jobs/add-job-target-companies /api-reference/openapi-v1.json post /v1/jobs/{id}/target-companies Add companies to a job target company list in bulk. Resolve company IDs with POST /v1/companies/search first. Invalid company IDs fail individually and do not block other valid IDs in the same request. # Create job Source: https://docs.stardex.com/api-reference/jobs/create-job /api-reference/openapi-v1.json post /v1/jobs Create a new job with company association, pipeline template, and team member assignments. The company will be matched or created automatically based on the identifiers provided. Optionally assign `job_status_id` from GET /v1/jobs/statuses (defaults to the team default status). Optionally link existing deals by passing deal_ids — each deal must belong to the same team (resolve IDs via POST /v1/deals/search). Optionally link existing client contacts by passing client_contact_ids — each contact must belong to the same team (resolve IDs via POST /v1/client-contacts). Background AI tasks (candidate search, criteria generation) are triggered after creation. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident. # Get job by ID Source: https://docs.stardex.com/api-reference/jobs/get-job-by-id /api-reference/openapi-v1.json get /v1/jobs/{id} Retrieve detailed information about a specific job including pipeline stages, team members with roles, candidate count, custom field values, linked client contacts, linked CRM deals, and fee & placement data (retainer structure, billing events, and total placement fee from the "Fees and Placements" section). For API-key callers, `linked_deals` requires `deals:read` and fee & placement data requires `compensation:read`; inaccessible sections are omitted. # Get job documents Source: https://docs.stardex.com/api-reference/jobs/get-job-documents /api-reference/openapi-v1.json get /v1/jobs/{id}/documents Retrieve a paginated list of documents attached to a job, including job descriptions, contracts, offer letters, and legal documents. Stored files receive short-lived signed download URLs; re-fetch when a URL expires. Pass include_text=true to receive extracted plain-text content when it is available. # List job applicants Source: https://docs.stardex.com/api-reference/jobs/list-job-applicants /api-reference/openapi-v1.json get /v1/jobs/{id}/applicants Retrieve a paginated list of inbound applications submitted through the public job posting form (the Applicants tab). This is **not** the job pipeline. Pipeline candidates — people already added to a stage — are returned by `GET /v1/jobs/{id}/candidates`. **Status values**: `new` (unprocessed), `selected` (added to the job pipeline; `person_id` is then set), `not_a_fit` (rejected from the Applicants tab). File fields and `resume_url` / `cover_letter_url` are short-lived signed download URLs. Re-fetch this endpoint when a URL expires (about 15 minutes). Jobs with no public posting return an empty list. Unknown job IDs return 404. # List job candidates Source: https://docs.stardex.com/api-reference/jobs/list-job-candidates /api-reference/openapi-v1.json get /v1/jobs/{id}/candidates Retrieve a paginated list of ALL candidates in a specific job — no filtering. **When to use**: Only when you need every candidate regardless of stage, tags, or other criteria. **For filtered queries** (by pipeline stage, custom attributes/tags, name, location, etc.), use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead — it supports all person search filters and can return candidate-level fields in a single call. **Inbound applications** (Applicants tab) are a separate resource — use `GET /v1/jobs/{id}/applicants`. # List job document types Source: https://docs.stardex.com/api-reference/jobs/list-job-document-types /api-reference/openapi-v1.json get /v1/jobs/document-types Returns every active job document type for the organization, ordered by name. No pagination — the full list is always returned. Document types are configurable per organization, so the available keys differ between organizations. Call this to discover valid `document_types` values for `GET /v1/jobs/{id}/documents` and valid `type` values when uploading a document. # List job statuses Source: https://docs.stardex.com/api-reference/jobs/list-job-statuses /api-reference/openapi-v1.json get /v1/jobs/statuses Retrieve all job statuses for the team, including each status's lifecycle category (`status_type`: not_started, in_progress, closed_won, or closed_lost). Use the returned `id` values when filtering by `job_status_ids_included` in POST /v1/jobs/search or assigning `job_status_id` in POST /v1/jobs or PATCH /v1/jobs/{id}. # List job team member roles Source: https://docs.stardex.com/api-reference/jobs/list-job-team-member-roles /api-reference/openapi-v1.json get /v1/jobs/team-member-roles Retrieve all job team member roles for the current team. Use the returned `id` values when filtering by `team_member_role_ids` in `POST /v1/jobs/search` or `POST /v1/persons/search`. Roles are returned in display order (`position` ascending). Every team has at least one owner role (e.g. "Team Lead") indicated by `is_owner_role: true`. # List jobs (deprecated) Source: https://docs.stardex.com/api-reference/jobs/list-jobs-deprecated /api-reference/openapi-v1.json get /v1/jobs **Deprecated** — Use `POST /v1/jobs/search` instead for full filtering, sorting, and vector search. Retrieve a paginated list of jobs with team members and candidate counts. Optionally filter by archive status (`is_archived`) and/or team member and role (e.g. "Executive Sponsor"). **Include control**: The `include` query param accepts a comma-separated list. Allowed values: `custom_fields`, `linked_deals`, `fees`, `client_contacts`. When omitted, no extra sections are returned. For API-key callers, `linked_deals` requires `deals:read` and `fees` requires `compensation:read`; inaccessible sections are omitted. **Note**: This endpoint does NOT return pipeline stages. To get a job's pipeline stage IDs and names (needed for stage-based filtering in person search), use `GET /v1/jobs/{id}` instead. # List pipeline stages Source: https://docs.stardex.com/api-reference/jobs/list-pipeline-stages /api-reference/openapi-v1.json get /v1/jobs/pipeline-stages Retrieve all candidate pipeline stages for the team, including Stardex stage categories (`is_rejection_stage`, `is_interviewing_stage`, `is_offer_stage`, `is_placement_stage`). Use the returned `id` values when filtering persons by pipeline stage or moving candidates with POST /v1/candidates/update-stage. Stages are returned in display order (`stage_order` ascending). This is the team-level catalog; a job's ordered stages also appear on GET /v1/jobs/{id}. # Remove job target companies Source: https://docs.stardex.com/api-reference/jobs/remove-job-target-companies /api-reference/openapi-v1.json delete /v1/jobs/{id}/target-companies Remove companies from a job target company list in bulk. Resolve company IDs with POST /v1/companies/search first. Invalid company IDs fail individually and do not block other valid IDs in the same request. # Search jobs Source: https://docs.stardex.com/api-reference/jobs/search-jobs /api-reference/openapi-v1.json post /v1/jobs/search Advanced job search with filtering, sorting, and vector search. Supports all filter types: keywords, location, job status, companies, team members/roles, custom attributes (select, numeric, date, team member), and semantic vector search. **AI AGENTS — Use `vector_search` if the user is inquiring about roles by title or title and company. Do not use `keywords`.** Job titles have many equivalent forms ("VP of Engineering", "VP Engineering", "Engineering VP", "Head of Engineering") — keywords will silently miss them . Vector search handles all variants automatically. The exception: a verbatim job ID/code lookup where you need an exact internal reference (e.g. "find the jobID 1234"). **Archive filter (`is_archived`)**: Omit to include both active and archived jobs (recommended for similar past searches, comps, pitch prep, company/sector history). Pass `false` for active jobs only; `true` for archived only. Always surface archive/status in answers. **Vector search**: Pass `vector_search` with a text query (min 5 chars) for AI-powered semantic search. **Date range filters**: Use `created_at_gte`/`created_at_lte` and `updated_at_gte`/`updated_at_lte` to filter by creation or modification timestamps. **Custom attribute filters**: Use `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`, `company_attribute_filters` for custom field filtering. **Include control**: Pass `include: ["custom_fields", "linked_deals", "fees", "client_contacts", "pipeline_stages"]` to embed custom field values, linked deals, fee & placement data, client contacts, and/or pipeline stages in each job. For API-key callers, `linked_deals` requires `deals:read` and `fees` requires `compensation:read`; inaccessible sections are omitted. AI AGENTS — Result processing: After receiving results, reason and process them before presenting to the user. Only show jobs where the title genuinely matches what the user asked for. For example, if the user asks for "VP of Engineering" roles, exclude results like "VP Consumer Electronics" or "SVP Sales Engineering" — these are not engineering leadership roles. Show relevant results rather than regurgitating everything the vector search returns. # Update job Source: https://docs.stardex.com/api-reference/jobs/update-job /api-reference/openapi-v1.json patch /v1/jobs/{id} Update fields on an existing job (title, job_description, status, location, salary range, salary details, billing contact name/email, fee, dates, archive state, linked deals, linked client contacts, custom fields). Use GET /v1/jobs/statuses for valid status IDs, GET /v1/custom-fields/jobs for custom field attribute IDs, and POST /v1/deals/search to resolve deal_ids for linking. Passing deal_ids fully replaces all existing deal_jobs links for the job; passing client_contact_ids fully replaces the client contacts on the job. Changes made through the API only start automations that are set to run on API and MCP changes (runs_on_api_changes), so one call cannot start runs across hundreds of records by accident. # Upload job document Source: https://docs.stardex.com/api-reference/jobs/upload-job-document /api-reference/openapi-v1.json post /v1/jobs/{id}/documents Upload a document for a job. Supports two modes: **1. Direct file upload** (`Content-Type: multipart/form-data`): Send the file in a `file` field with `title` and `type` metadata fields. Allowed file types: PDF, DOC, DOCX, PNG, JPG, JPEG. Max size: 25 MB. **2. JSON body** (`Content-Type: application/json`): Provide a `file_url` — a publicly accessible HTTPS URL. The server downloads the file, validates it, and stores it. # Add list items Source: https://docs.stardex.com/api-reference/lists/add-list-items /api-reference/openapi-v1.json post /v1/lists/{id}/items Add persons or companies to a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request. Soft-deleted memberships are restored instead of duplicated. **Person-list auto-tagging**: When people are added or restored to a person list with list-scoped AI fields, background AI auto-tagging starts after this request completes. The response does not wait for tagging, and a successful list mutation does not guarantee that background tagging finishes successfully. # Create list Source: https://docs.stardex.com/api-reference/lists/create-list /api-reference/openapi-v1.json post /v1/lists Create a new saved list. Lists can hold either persons or companies, determined by `list_type`. Optionally link to a job, person, or company. # Get list by ID Source: https://docs.stardex.com/api-reference/lists/get-list-by-id /api-reference/openapi-v1.json get /v1/lists/{id} Retrieve a single list by UUID with its paginated items. Items are paginated via `items_offset` and `items_limit` query parameters. Each item includes the referenced person or company details depending on the list type. # Remove list items Source: https://docs.stardex.com/api-reference/lists/remove-list-items /api-reference/openapi-v1.json delete /v1/lists/{id}/items Soft-remove persons or companies from a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request. # Search lists Source: https://docs.stardex.com/api-reference/lists/search-lists /api-reference/openapi-v1.json post /v1/lists/search Search and filter saved lists with pagination and sorting. **Filters**: `keywords` (name search), `list_type`, `is_archived`, `owner_ids`, `is_public`. **Sorting**: `name`, `created_at`, `updated_at`, `item_count`. Returns list metadata with item counts, owners, and creator info. # Get meeting recording by ID Source: https://docs.stardex.com/api-reference/meeting-recordings/get-meeting-recording-by-id /api-reference/openapi-v1.json get /v1/meeting-recordings/{id} Retrieve detailed information about a specific meeting recording including the associated calendar meeting details and full transcript text. The `transcript_text` field is always included. It will be null if the recording has not finished processing or no transcript was generated. # List meeting recordings Source: https://docs.stardex.com/api-reference/meeting-recordings/list-meeting-recordings /api-reference/openapi-v1.json get /v1/meeting-recordings Retrieve a paginated list of meeting recordings with optional filters. **Filters**: `processing_status`, `calendar_meeting_id`, `meeting_started_after`, `meeting_started_before` (ISO 8601 date range). **Sorting**: `sort_by` (meeting_started_at, created_at, recording_duration_seconds) with `sort_order` (asc/desc, default desc). **Pagination**: Use `offset` and `limit` query params (max 100 per page). # Create person activity Source: https://docs.stardex.com/api-reference/person-activities/create-person-activity /api-reference/openapi-v1.json post /v1/person-activities Create a new activity (note, meeting, email, etc.) and attach it to a person record. The person can be identified by `person_id`, `email`, `linkedin_url`, or `full_name` — at least one is required. **Job association**: Pass optional `job_id` to link the activity to a specific search. When `job_id` is provided, the identified person must already be a candidate on that job; otherwise the request returns a 400 error. **Event time**: Optional `occurred_at` records when the event actually happened (ISO 8601). This is distinct from `created_at`, a system-managed timestamp for when the activity record was written — `created_at` cannot be set by the caller. If `occurred_at` is omitted, it defaults to `created_at`. **Attribution**: session and OAuth callers are always recorded as themselves. Pass `team_member_id` only when authenticating with an API key. **Supported activity types**: `secondary_note` (general note), `meeting_note`, `meeting_transcript`, `email`, `interview_note`, `linkedin_message`, `text_message`, `candidate_summary`, `linkedin_message_response`, `call_note`. # Delete person activity by ID Source: https://docs.stardex.com/api-reference/person-activities/delete-person-activity-by-id /api-reference/openapi-v1.json delete /v1/person-activities/{id} Remove a person activity from the person timeline. Deleted activities cannot be retrieved or updated. # Get person activity by ID Source: https://docs.stardex.com/api-reference/person-activities/get-person-activity-by-id /api-reference/openapi-v1.json get /v1/person-activities/{id} Retrieve a single physical person activity by its UUID. Returns content in both HTML and plain text formats, plus `created_at` (system-managed record-write time) and `occurred_at` (when the event happened). Synthetic timeline activities, including `pipeline_status` entries, are not stored in `person_activities` and cannot be fetched from this endpoint. **When to use**: Use when you need the full content of a specific activity. For a paginated timeline of all activities for a person, use `GET /v1/persons/{id}/activities` instead. # List person activity types Source: https://docs.stardex.com/api-reference/person-activities/list-person-activity-types /api-reference/openapi-v1.json get /v1/person-activities/types Returns every activity type registered for the requesting team, including built-in types (e.g. `secondary_note`, `email`, `meeting_note`) and any custom types defined under Settings → Activity Types. No pagination — the full list is returned in a single response. **When to use**: Call this before creating an activity with a custom `activity_type`, or before filtering `GET /v1/persons/{id}/activities` by `activity_types` / `excluded_activity_types`, so you know which keys are valid for the team. # Update person activity by ID Source: https://docs.stardex.com/api-reference/person-activities/update-person-activity-by-id /api-reference/openapi-v1.json patch /v1/person-activities/{id} Update an existing person activity. You can change the content, the activity type, the event time, or any combination. **Content**: Set `content_type` to `"text"` for plain text (auto-converted to HTML) or `"html"` for raw HTML input. **Activity type**: Pass `activity_type` to change the type. The new type must be registered for the team — discover valid types with `GET /v1/person-activities/types`. **Event time**: Optional `occurred_at` sets when the event actually happened (ISO 8601). This is distinct from `created_at`, which is system-managed and cannot be changed. At least one of `activity_content`, `activity_type`, or `occurred_at` must be provided. # Advanced person search Source: https://docs.stardex.com/api-reference/persons/advanced-person-search /api-reference/openapi-v1.json post /v1/persons/search The primary tool for finding and filtering persons across the entire database. All filters are optional and combinable. Use this instead of list-persons for any filtered query. **Direct search fields**: `email` (exact match), `name` (ranked lookup on name, title, company, and location; top matches, not exhaustive), `phone` (tiered matching: exact → normalized → last-7-digits), `linkedin_url` (exact profile match), `vector_search` (AI semantic search, min 5 chars). **Filter categories**: jobs & pipeline stages, job titles, departments, companies (current/past), activity types, owners & dates, activity content keywords, owners (person/candidate), source, lists, contact presence, engagement recency, date ranges (created_at, updated_at, added-to-job), locations, and custom attributes (select, numeric, date, team member, company). **Activity filters**: `activity_types_*`, `activity_owner_ids_*` and `activity_date_*` all apply to the same activity. For example, `activity_types_included: [""]` with `activity_date_type: "within_last"`, `activity_date_value: 7`, `activity_date_unit: "days"` returns persons with an activity of that type in the last 7 days. With only `activity_types_excluded` set, the owner and date filters scope the exclusion instead (persons with no activity of that type in the window). Get type keys from `GET /v1/person-activities/types` and team member IDs from `GET /v1/team-members`. **Custom field / tag filtering**: To filter by person tags or select-type attributes (e.g. "banking" tag), use `select_attribute_filters` with `attribute_id` and `values` (tag UUIDs). To discover attribute IDs and tag option IDs, call `GET /v1/custom-fields/persons` first. **Sorting**: Set `sort_by` to one of: `name`, `created_at`, `updated_at`, `current_job_title`, `company`, `location`, `date_of_last_engagement`, `person_owner`, `last_activity_type`, `contact_email`, or `custom_`. Job-context sort columns (require `job_id` or exactly 1 job in `job_ids_included`): `pipeline_stage`, `stage_date`, `added_to_job_at`, `rating`, `rating_note`, `candidate_owner`. Use `sort_order` (`asc` or `desc`, default `desc`). **Include control**: The `include` body array controls which sections appear in each person record. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `related_people`, `offers`. When omitted, returns only base fields (id, name, emails, phones, preferred_email, preferred_phone, current_job_title, etc.). Pass an empty array `[]` to explicitly request base fields only. **API-key scope requirements**: Requests missing a required scope succeed with inaccessible include sections omitted: `activities` requires `notes:read`, `candidates` requires `candidates:read`, and `compensation` and `offers` require `compensation:read`. `activity_content_keywords` searches note and document text, so API keys must hold both `notes:read` and `documents:read` or the request is rejected. **Job-scoped search**: Pass `job_id` to scope results to candidates in a specific job. This enables job-context sort columns and automatically filters to persons in that job. Combine with `include: ["candidates"]` to get candidate-level fields (pipeline stage, sourced_by, etc.). # Create person Source: https://docs.stardex.com/api-reference/persons/create-person /api-reference/openapi-v1.json post /v1/persons Create a new person record with contact details and optional job association. Returns the created person with IDs for further operations. Pass `custom_fields` to set custom field values in the same call, and `sourced_by` with `job_id` to record which team member sourced the candidate. **Warning:** `linkedin_url` is optional but **strongly recommended**. It is the only reliable deduplication key for this endpoint. When provided, an existing person with that LinkedIn profile is matched and updated (never duplicated). **Omitting it will create a new person even if the same person already exists** (including matches on name or email), leading to more duplicates. Prefer `PATCH /v1/persons/{id}` when you already have the person ID. # Create person compensation Source: https://docs.stardex.com/api-reference/persons/create-person-compensation /api-reference/openapi-v1.json post /v1/persons/{id}/compensations Create a compensation history record for a person. Use this for current, desired, or minimum compensation details. If `job_id` is provided, the person must already be a candidate on that job. # Delete person compensation Source: https://docs.stardex.com/api-reference/persons/delete-person-compensation /api-reference/openapi-v1.json delete /v1/persons/{id}/compensations/{compensation_id} Delete one compensation history record from a person. # Get person by ID Source: https://docs.stardex.com/api-reference/persons/get-person-by-id /api-reference/openapi-v1.json get /v1/persons/{id} Retrieve detailed information about a specific person by their UUID. **Include control**: The `include` query param accepts a comma-separated list of section names to control the response shape. Allowed values: `work_experience`, `education_experience`, `certifications`, `candidates`, `custom_fields`, `activities`, `compensation`, `related_people`, `offers`. When omitted, defaults to: `work_experience`, `education_experience`, `certifications`, `custom_fields`. Pass an empty string to return only base fields (id, name, emails, phones, preferred_email, preferred_phone, current_job_title, etc.). Note: The `activities` section returns up to 50 most recent activities. For full pagination, use `GET /v1/persons/{id}/activities`. **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`. # Get unified person activities Source: https://docs.stardex.com/api-reference/persons/get-unified-person-activities /api-reference/openapi-v1.json get /v1/persons/{id}/activities Retrieve a unified, paginated timeline of all activities for a person. Aggregates notes, emails, tasks, calendar events, sequence enrollments, pipeline stage changes, and assessments. Each item includes `created_at` (when the record was written) and `occurred_at` (when the event happened), and the timeline is ordered by `occurred_at` descending. Supports filtering by activity type, team member, job, date range (created_at_gte / created_at_lte), and text search. **When to use**: Use this for full activity pagination with filtering. You can also pass `include=activities` when calling `GET /v1/persons/{id}` for a simpler response. # List persons (deprecated) Source: https://docs.stardex.com/api-reference/persons/list-persons-deprecated /api-reference/openapi-v1.json get /v1/persons **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. **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`. # Update person Source: https://docs.stardex.com/api-reference/persons/update-person /api-reference/openapi-v1.json patch /v1/persons/{id} Update an existing person's information including contact details, job title, company, do-not-contact status, and custom field values. Only provided fields are updated; omitted fields remain unchanged. # Update person compensation Source: https://docs.stardex.com/api-reference/persons/update-person-compensation /api-reference/openapi-v1.json patch /v1/persons/{id}/compensations/{compensation_id} Update one compensation history record for a person. Only provided fields are changed; pass null for nullable fields to clear them. # Ringover Integration Source: https://docs.stardex.com/help-center/ringover-integration Connect Ringover to Stardex for click-to-call, SMS, and automatic call transcript logging on candidate and contact profiles. ## Overview The Ringover integration connects your team's Ringover phone system to Stardex, giving you: * **Click-to-call** — dial any phone number directly from a person's profile * **Send SMS** — compose and send text messages without leaving Stardex * **Automatic transcript sync** — call transcripts are logged as activities on the matching person's timeline * **Recording links** — links to Ringover-hosted call recordings appear alongside each transcript Ringover is an org-wide integration — once an admin connects it, every team member can use the in-app dialer after signing into their Ringover account. Only one voice integration (Ringover or RingCentral) can be active per team at a time. If you already use RingCentral, you'll need to disconnect it before enabling Ringover. *** ## Setup (Admin Only) You'll need admin access to both Stardex and your Ringover Dashboard. The setup takes about five minutes. ### Step 1 — Enable the integration 1. Go to **Settings → Voice Integrations** in Stardex. 2. Find **Ringover** and toggle it **on**. ### Step 2 — Add the webhook URL in Ringover Once enabled, Stardex shows a **webhook URL**. Copy it, then: 1. Open your **Ringover Dashboard**. 2. Navigate to **Developer → Webhooks**. 3. Open the **Call Event** section. 4. Turn on **Activate webhook**. 5. Paste the copied URL into the **Transcription available** field (under After-Call Work). This is the only webhook event Stardex needs — contacts are matched automatically by phone number. ### Step 3 — Copy your webhook key Still in the Ringover Dashboard's Call Event section: 1. Copy the **Key** shown at the top of the section. 2. Go back to Stardex and paste it into the **Webhook key** field. ### Step 4 — Create and add your API key 1. In the Ringover Dashboard, go to **Developer → API keys**. 2. Create a new key with the **Calls Read** permission. 3. Copy the key and paste it into the **API key** field in Stardex. Your region (EU or US) is detected automatically from the API key. ### Step 5 — Save & Connect Click **Save & Connect**. If the credentials are valid, the status badge will change to **Connected** and transcript syncing begins immediately. *** ## Using the Dialer Once the integration is active, a floating **phone button** appears in the bottom-right corner of every page. Click it to open the Ringover dialer. * **Sign in** to your Ringover account inside the dialer the first time. * The dialer is **draggable** — move it anywhere on screen. Your position is remembered. * The dialer **opens automatically** when you receive an incoming call. * Click the **X** to minimize back to the floating phone button. ### Click-to-call from a profile 1. Open any person's profile. 2. Click the **actions menu** (or the phone icon next to a phone number). 3. Select **Call** — the dialer opens and dials the number automatically. ### Send an SMS from a profile 1. Open any person's profile. 2. Click the **actions menu** next to a phone number. 3. Select **Send Text** — the dialer opens with an SMS compose window. If the Ringover dialer isn't loaded (e.g. pop-ups are blocked), clicking Call or Send Text opens the Ringover web app in a new tab as a fallback. *** ## How Transcript Sync Works After a call ends, Ringover generates a transcript (this depends on your Ringover plan supporting transcription). Once the transcript is ready, Stardex automatically: 1. **Receives the webhook** from Ringover. 2. **Fetches the full transcript and call details** from the Ringover API. 3. **Matches the external caller/callee** to a person in Stardex by phone number. 4. **Creates a Call Note activity** on the matched person's timeline containing: * A link to **view the call in Ringover** * A link to the **call recording** (if available) * **Participant names** (agent and contact) * The **full transcript** with speaker labels and timestamps ### Person matching * If the phone number matches **exactly one** person in Stardex, the activity is linked to that person. * If there are **zero matches or multiple matches**, the activity is saved as an **unassigned activity** so nothing is lost — you can manually link it later. ### Idempotent processing If Ringover sends the same webhook more than once (e.g. due to a retry), Stardex updates the existing activity rather than creating a duplicate. *** ## Important Notes * **Call recordings are linked, not stored.** Stardex includes a link to the Ringover-hosted recording in the activity but does not download or store the audio file. Your recordings stay in Ringover. * **Transcription requires a compatible Ringover plan.** If your Ringover plan does not include transcription, the webhook won't fire and no activities will be created. * **Phone numbers must be on the person record.** Transcript sync matches by phone number, so make sure your candidates and contacts have phone numbers saved in Stardex. *** ## Disconnecting To disconnect the integration: 1. Go to **Settings → Voice Integrations**. 2. Click **Disconnect Ringover**. 3. Confirm the disconnection. After disconnecting in Stardex, remember to also **remove the webhook URL** from your Ringover Dashboard to stop webhook deliveries. Existing call note activities will remain on person timelines — disconnecting only stops future syncing. # Using Stardex CRM for Business Development Source: https://docs.stardex.com/help-center/using-stardex-crm-for-business-development Learn how to use Stardex as a CRM to manage your firm's business development pipeline — from tracking deals and client companies to adding contacts and converting won deals into active searches.