# Popp AI Documentation > Documentation for Popp AI ## Guides: popp guide - [API Key Management](https://docs.joinpopp.com/docs/api-key-management.md) - [Quickstart](https://docs.joinpopp.com/docs/quickstart.md): Get up and running with the Popp API. - [Campaigns](https://docs.joinpopp.com/docs/campaigns-guide.md) - [Job Application Flow](https://docs.joinpopp.com/docs/applicant-outreach-flow.md) - [Document Collection Flow](https://docs.joinpopp.com/docs/document-collection-flow.md) - [Conversations](https://docs.joinpopp.com/docs/conversations-guide.md) - [Documents](https://docs.joinpopp.com/docs/documents-guide.md) - [Analysis](https://docs.joinpopp.com/docs/analysis-guide.md) - [Scheduling](https://docs.joinpopp.com/docs/scheduling-overview.md) - [Meeting Templates](https://docs.joinpopp.com/docs/meeting-templates.md) - [Scheduling Campaigns](https://docs.joinpopp.com/docs/scheduling-campaigns.md) - [Auto-Schedule Conversations](https://docs.joinpopp.com/docs/auto-schedule-conversations.md) - [Scheduling with Availability Collection](https://docs.joinpopp.com/docs/scheduling-with-availability-collection.md) - [Workflow Builder](https://docs.joinpopp.com/docs/workflow-builder-guide.md) - [Workflow Configuration](https://docs.joinpopp.com/docs/workflow-configuration.md) - [Authentication](https://docs.joinpopp.com/docs/authentication-guide.md) - [Webhooks](https://docs.joinpopp.com/docs/webhooks.md) - [Webhook Event Structure](https://docs.joinpopp.com/docs/webhook-event-structure.md) - [Webhook Authentication with SHA256](https://docs.joinpopp.com/docs/webhook-authentication.md) - [Conversation Events](https://docs.joinpopp.com/docs/conversation-events.md) - [Analysis Events](https://docs.joinpopp.com/docs/analysis-events.md) - [Scheduling Events](https://docs.joinpopp.com/docs/scheduling-events.md) - [Workflow Events](https://docs.joinpopp.com/docs/workflow-events.md) - [Candidate Processing Events](https://docs.joinpopp.com/docs/candidate-processing-events.md) - [Candidate Deletion Events](https://docs.joinpopp.com/docs/candidate-deletion-events.md) - [Candidate List Events](https://docs.joinpopp.com/docs/candidate-list-events.md) - [Webhook Management](https://docs.joinpopp.com/docs/webhook-management.md) - [Custom Fields (Beta)](https://docs.joinpopp.com/docs/custom-fields-guide.md) ## Guides: MCP Server - [MCP](https://docs.joinpopp.com/docs/mcp.md) ## API Reference: Popp API - Conversations - [Create conversation](https://docs.joinpopp.com/reference/create-conversation.md): Creates a conversation in Popp application - [List conversations](https://docs.joinpopp.com/reference/list-conversations.md): List all conversations in Popp application - [Get conversation](https://docs.joinpopp.com/reference/get-conversation.md): Get a conversation - [List conversation messages](https://docs.joinpopp.com/reference/list-conversation-messages.md): List all messages in a conversation - [Send Conversation Message](https://docs.joinpopp.com/reference/send-conversation-message.md): Send a message as the user/recruiter on a conversation - [Takeover Conversation](https://docs.joinpopp.com/reference/takeover-conversation.md): Take over a conversation from the AI agent so a human can respond directly - [Hand Conversation to Agent](https://docs.joinpopp.com/reference/hand-conversation-to-agent.md): Hand the conversation back to the AI agent after a human takeover - [Bulk create conversations](https://docs.joinpopp.com/reference/bulk-create-conversations.md): Creates multiple conversations in bulk for a single campaign - Campaigns - [Get campaign](https://docs.joinpopp.com/reference/get-campaign.md): Get a campaign - [Create Campaign](https://docs.joinpopp.com/reference/create-campaign.md): Creates a campaign in Popp application. - [List campaigns](https://docs.joinpopp.com/reference/list-campaigns.md): List all campaigns in Popp application - [Generate Questions](https://docs.joinpopp.com/reference/generate-questions.md): Generates interview questions from a job description using Popp agent - [Stop Campaign](https://docs.joinpopp.com/reference/stop-campaign.md): Stops a campaign and optionally sends a cancellation message to candidates - [Update Campaign](https://docs.joinpopp.com/reference/update-campaign.md): Updates an existing campaign. All fields are optional but at least one must be provided. Questions cannot be updated after creation. Setting campaignStatus to ARCHIVED will stop the campaign. Setting… - [Generate Preferred Answer Requirements](https://docs.joinpopp.com/reference/generate-preferred-answer-requirements.md): Turns a campaign question and its preferred answer into a list of scoring statements. The returned list can be posted straight back as that question's preferredAnswerRequirements on create or update… - Documents - [Get document](https://docs.joinpopp.com/reference/get-document.md): Get a document - [List conversation documents](https://docs.joinpopp.com/reference/list-conversation-documents.md): List documents in a conversation - [Get document media](https://docs.joinpopp.com/reference/get-document-media.md): Get the media of a document - [Download media](https://docs.joinpopp.com/reference/download-media.md): Download the content of a media - [Process Document (Beta)](https://docs.joinpopp.com/reference/process-document.md): **Beta** — endpoint shape and validation rules may evolve before general availability. Classify and validate an uploaded document. Two modes are supported and exactly one of the two must be present… - [List document types (Beta)](https://docs.joinpopp.com/reference/list-document-types.md): **Beta:** this endpoint is still in active development; response shape and filter behaviour may change. Searches the document types for the caller's organization. Backed by OpenSearch — supports… - [Create a document type (Beta)](https://docs.joinpopp.com/reference/create-document-type.md): **Beta:** this endpoint is still in active development; payload shape and validation rules may change. Creates a document type in the caller's organization. The name is required; everything else is… - [Get a document type by ID (Beta)](https://docs.joinpopp.com/reference/get-document-type.md): **Beta:** this endpoint is still in active development; response shape may change. Fetches a single document type by its ID. Returns 404 if the document type does not exist or belongs to a different… - [Update a document type (Beta)](https://docs.joinpopp.com/reference/update-document-type.md): **Beta:** this endpoint is still in active development; payload shape and validation rules may change. Partially updates a document type. Pass only the fields you want to change. To clear a nullable… - [Delete a document type (Beta)](https://docs.joinpopp.com/reference/delete-document-type.md): **Beta:** this endpoint is still in active development. Hard-deletes a document type. Rejected with 409 if the document type is referenced by any campaign or workflow — archive it instead. Use this… - [Archive a document type (Beta)](https://docs.joinpopp.com/reference/archive-document-type.md): **Beta:** this endpoint is still in active development. Soft-deletes a document type by setting `isArchived: true`. Idempotent — archiving an already-archived document type returns 200 with the… - Templates - [List templates](https://docs.joinpopp.com/reference/list-templates.md): List all message templates belonging to the authenticated organization - Agents - [List agents](https://docs.joinpopp.com/reference/list-agents.md): List all agents belonging to the authenticated organization - Webhooks - [List Webhooks](https://docs.joinpopp.com/reference/list-webhooks.md): List all webhooks configured for the organization - [Create Webhook](https://docs.joinpopp.com/reference/create-webhook.md): Create a new webhook for the organization. Subscribing to an event that is not yet available returns 400. - [Update Webhook](https://docs.joinpopp.com/reference/update-webhook.md): Update an existing webhook configuration. Subscribing to an event that is not yet available returns 400. - [Delete Webhook](https://docs.joinpopp.com/reference/delete-webhook.md): Delete a webhook configuration - [List Webhook Events](https://docs.joinpopp.com/reference/list-webhook-events.md): List all webhook event types available for subscription, with their descriptions and categories - Organization Configuration - [Get organization configuration](https://docs.joinpopp.com/reference/get-organization-config.md): Get an organization configuration - [Create Organization Config](https://docs.joinpopp.com/reference/create-organization-config.md): Creates an Organization Config - [Update organization configuration](https://docs.joinpopp.com/reference/update-organization-config.md): Updates an organization configuration - [Get organization configuration by external organization id](https://docs.joinpopp.com/reference/get-organization-config-by-external-id.md): Returns the configuration for the organization matching your own organization id, scoped to your organization group. Returns 409 if the external id matches more than one organization. - [Update organization configuration by external organization id](https://docs.joinpopp.com/reference/update-organization-config-by-external-id.md): Creates or updates the configuration for the organization matching your own organization id, scoped to your organization group. Returns 409 if the external id matches more than one organization. - Analysis - [Create analysis candidate](https://docs.joinpopp.com/reference/create-analysis-candidate.md): Queues a CV or questionnaire for scoring against an analysis. - [Generate requirements](https://docs.joinpopp.com/reference/generate-requirements.md): Uses AI to extract requirements from a job description. Stateless - does not create or modify any data. - [Create analysis](https://docs.joinpopp.com/reference/create-analysis.md): Creates a new analysis with the given title, job description, and requirements. Immediately starts processing. - [List analyses](https://docs.joinpopp.com/reference/list-analyses.md): Lists the organization's analyses, with optional filtering. Analyses managed by Workflow Builder (`isWorkflowManaged: true`) are left out. A page can hold fewer items than `limit`, or none, and still… - [Get analysis](https://docs.joinpopp.com/reference/get-analysis.md): Get a single analysis with full requirements - [Update analysis](https://docs.joinpopp.com/reference/update-analysis.md): Update analysis metadata (title, job description, external ID). Does not update requirements. - [Archive analysis](https://docs.joinpopp.com/reference/archive-analysis.md): Archives an analysis (soft delete). Only DRAFT or LIVE analyses can be archived. Archiving an already-archived analysis is idempotent. An analysis managed by Workflow Builder can't be archived here:… - [Update requirements and reanalyse](https://docs.joinpopp.com/reference/update-requirements-and-reanalyse.md): Replaces all requirements on the analysis and triggers re-analysis of existing candidates. Requirements with an ID are updated, without an ID are created, and existing requirements not in the array… - Scheduling - [Create auto-schedule conversation](https://docs.joinpopp.com/reference/create-scheduling-conversation.md): Creates a scheduling conversation in Popp application. This endpoint is used for meeting scheduling workflows where participants can provide their availability and a meeting will be scheduled… - [Invite Calendar Contact](https://docs.joinpopp.com/reference/invite-calendar-contact.md): Invites an external contact to connect their calendar. This sends an invitation to the contact allowing them to share their calendar availability. - [List meeting templates](https://docs.joinpopp.com/reference/list-meeting-templates.md): Search and list meeting templates belonging to the authenticated organization. All search filters are optional. Results are always scoped to the authenticated organization. **Note:** For full… - [Get meeting template](https://docs.joinpopp.com/reference/get-meeting-template.md): Get full details of a meeting template by ID. Returns the complete meeting template configuration including availability settings, buffer times, reminder settings, and participant information. Use… - [Create Meeting Template](https://docs.joinpopp.com/reference/create-meeting-template.md): Creates a calendar meeting template for scheduling meetings. The template defines meeting parameters such as duration, participants, availability, and video conferencing settings. - [Resend booking URL](https://docs.joinpopp.com/reference/resend-booking-url.md): Resends a booking URL to an existing conversation with updated meeting configuration. Use this when a candidate cannot find suitable time slots and you need to provide new availability options.… - [Update Meeting Template](https://docs.joinpopp.com/reference/update-meeting-template.md): Updates a calendar meeting template by ID. Nearly every field is required, so in practice a call supplies the template's whole configuration rather than a patch. The optional fields behave… - [Delete Meeting Template](https://docs.joinpopp.com/reference/delete-meeting-template.md): Deletes a calendar meeting template by ID. Returns 404 if the template does not exist, or if it belongs to a different organisation than the one tied to the API key. Returns 409 Conflict if the… - [Update Booking](https://docs.joinpopp.com/reference/update-booking.md): Update an existing booking. Supports updating the title, time, duration, description, location, and attendees of the meeting. The underlying calendar event is updated and participants are notified by… - [Get a calendar booking](https://docs.joinpopp.com/reference/get-booking.md): Get full details of a calendar booking by ID. Returns the booking record only if it belongs to the authenticated organization. - [List calendar bookings](https://docs.joinpopp.com/reference/list-bookings.md): List calendar bookings belonging to the authenticated organization. All filters are optional. Results are always scoped to the authenticated organization. Results are paginated using a cursor… - [Cancel Booking](https://docs.joinpopp.com/reference/cancel-booking.md): Cancel an existing booking. The underlying calendar event is cancelled via Nylas and a cancellation notification is sent to all participants by default. Returns 404 if the booking does not exist, or… - [Parse Availability](https://docs.joinpopp.com/reference/parse-availability.md): Parses natural-language availability text into structured time slots. Supports multi-turn clarification via the messages array. Does NOT save the availability — call PUT… - [Set User Calendar Availability](https://docs.joinpopp.com/reference/set-user-calendar-availability.md): Saves confirmed availability time slots to a participant's virtual calendar. Once all required participants for a meeting have availability recorded, the scheduling link is generated and sent to the… - [List User Calendars](https://docs.joinpopp.com/reference/list-user-calendars.md): List user calendars connected to the requesting organization. Use this to discover the `userCalendarId` needed to publish availability via PUT /v1/user-calendars/{userCalendarId}/availability. - [Get User Calendar](https://docs.joinpopp.com/reference/get-user-calendar.md): Fetch a single user calendar by id. Returns 404 if the calendar does not exist or does not belong to the requesting organization (the API does not leak existence across organizations). - Organizations - [List Organizations](https://docs.joinpopp.com/reference/list-organizations.md): List the organizations the authenticated user can access. Organization-group admins receive every organization in their group; other users receive the organizations they are a member of. This… - [Update Organization](https://docs.joinpopp.com/reference/update-organization-details.md): Update an organization's name and/or your own external identifier for it. Provide at least one field. Scoped to the organization group behind your API key; an organization in another group returns… - [Get Organization](https://docs.joinpopp.com/reference/get-organization-details.md): Get a single organization by id, including your own external identifier for it. Scoped to the organization group behind your API key; an organization in another group returns 404. Authenticated with… - Users - [Get User](https://docs.joinpopp.com/reference/get-user.md): Get a single user, with their per-organization access, by Popp user id. - [List Users](https://docs.joinpopp.com/reference/list-users.md): List the users in the organization group behind your API key (paginated), each with their per-organization access. - [Get User by Email](https://docs.joinpopp.com/reference/get-user-by-email.md): Get a single user, with their per-organization access, by email address. - [Update User](https://docs.joinpopp.com/reference/update-user.md): Update a user's name, organization access and/or group-level role. The organizations array uses replace-semantics (send the full desired set), while a field you omit is left unchanged; name each… - [Delete User](https://docs.joinpopp.com/reference/delete-user.md): Permanently delete a user. **This cannot be undone.** Their sign-in is removed, all organization access is revoked and their personal details are erased. Records they created, such as campaigns and… - [Create User](https://docs.joinpopp.com/reference/create-user.md): Create or invite a user with access to one or more organizations in the organization group behind your API key. Name each organization either by its Popp organizationId or by your own… - [Sign Out User](https://docs.joinpopp.com/reference/sign-out-user.md): Sign a user out of all of their active sessions. - [Sign Out User by Email](https://docs.joinpopp.com/reference/sign-out-user-by-email.md): Sign a user out of all of their active sessions, identified by email. - [List Organization Users](https://docs.joinpopp.com/reference/list-organization-users.md): List the users in a specific organization (paginated), each with their per-organization access. Scoped to the organization group behind your API key; an organization in another group returns 404.… - [Update User by Email](https://docs.joinpopp.com/reference/update-user-by-email.md): Update a user's name, organization access and/or group-level role, identified by email. The organizations array uses replace-semantics (send the full desired set), while a field you omit is left… - [Delete User by Email](https://docs.joinpopp.com/reference/delete-user-by-email.md): Permanently delete a user, identified by email. **This cannot be undone.** Their sign-in is removed, all organization access is revoked and their personal details are erased. Records they created,… - [Deactivate User by Email](https://docs.joinpopp.com/reference/deactivate-user-by-email.md): Deactivate a user, identified by email: revoke all of their organization access and disable their sign-in, keeping the account so it can be restored. The user still resolves by id and by email with… - [Reactivate User by Email](https://docs.joinpopp.com/reference/reactivate-user-by-email.md): Restore a deactivated user, identified by email: re-enable their sign-in and give them access to the organizations in the request body. That access is the set they end up with, not an addition to… - [Deactivate User](https://docs.joinpopp.com/reference/deactivate-user.md): Deactivate a user: revoke all of their organization access and disable their sign-in, keeping the account so it can be restored. The user still resolves by id and with an empty organizations array,… - [Reactivate User](https://docs.joinpopp.com/reference/reactivate-user.md): Restore a deactivated user: re-enable their sign-in and give them access to the organizations in the request body. That access is the set they end up with, not an addition to whatever they held… - Workflows - [Create workflow](https://docs.joinpopp.com/reference/create-workflow.md): Creates a workflow in the `UNPUBLISHED` state. It accepts runs once you [publish](/reference/publish-workflow) it. [Workflow configuration](/docs/workflow-configuration) describes the… - [List workflows](https://docs.joinpopp.com/reference/list-workflows.md): Lists your organization's workflows, most recently updated first. - [Get workflow](https://docs.joinpopp.com/reference/get-workflow.md): Returns a workflow by ID, including its full `configuration` and `settings` JSON strings. - [Update workflow](https://docs.joinpopp.com/reference/update-workflow.md): Updates the working draft of a workflow. Changes go live only when you [publish](/reference/publish-workflow). Some checks, such as [analysis node… - [Get workflow by external ID](https://docs.joinpopp.com/reference/get-workflow-by-external-id.md): Same as [Get workflow](/reference/get-workflow), but finds the workflow by your external ID. - [Update workflow by external ID](https://docs.joinpopp.com/reference/update-workflow-by-external-id.md): Same as [Update workflow](/reference/update-workflow), but finds the workflow by your external ID. - [Get candidate profile by external ID](https://docs.joinpopp.com/reference/get-candidate-profile-by-external-id.md): Returns the candidate profile in the caller's organization group with the given external ID. Returns 404 when no profile matches. - [Publish workflow by external ID](https://docs.joinpopp.com/reference/publish-workflow-by-external-id.md): Same as [Publish workflow](/reference/publish-workflow), but finds the workflow by your external ID. - [Archive workflow by external ID](https://docs.joinpopp.com/reference/archive-workflow-by-external-id.md): Same as [Archive workflow](/reference/archive-workflow), but finds the workflow by your external ID. - [Pause workflow by external ID](https://docs.joinpopp.com/reference/pause-workflow-by-external-id.md): Same as [Pause workflow](/reference/pause-workflow), but finds the workflow by your external ID. - [Resume workflow by external ID](https://docs.joinpopp.com/reference/resume-workflow-by-external-id.md): Same as [Resume workflow](/reference/resume-workflow), but finds the workflow by your external ID. - [Start workflow runs by external ID](https://docs.joinpopp.com/reference/start-workflow-runs-by-external-id.md): Same as [Start workflow runs](/reference/start-workflow-runs), but finds the workflow by your external ID. - [Publish workflow](https://docs.joinpopp.com/reference/publish-workflow.md): Publishes the workflow's working draft as a new live version. Popp checks the draft first, and a failed publish changes nothing. [Configuration… - [Archive workflow](https://docs.joinpopp.com/reference/archive-workflow.md): Archives a workflow. An archived workflow can't be edited, published or used to start runs, and archiving can't be undone. Runs in progress continue to completion. - [Pause workflow](https://docs.joinpopp.com/reference/pause-workflow.md): Pauses a published workflow. It stops accepting new runs, and runs in progress continue. [Resume](/reference/resume-workflow) it to accept new runs again. - [Resume workflow](https://docs.joinpopp.com/reference/resume-workflow.md): Returns a paused workflow to `PUBLISHED`, so it accepts new runs again. - [Start workflow runs](https://docs.joinpopp.com/reference/start-workflow-runs.md): Enrols candidates in a published workflow, one run per candidate. Runs start after the call returns, so the response reports what Popp accepted rather than the runs. Follow the runs with [List… - [List workflow runs](https://docs.joinpopp.com/reference/list-workflow-runs.md): Lists a workflow's runs. Each run includes the candidate's name, so you don't need a call per run to look the candidate up. - [Get workflow run](https://docs.joinpopp.com/reference/get-workflow-run.md): Returns a workflow run by ID, including its full `context` JSON string. - [Cancel workflow run](https://docs.joinpopp.com/reference/cancel-workflow-run.md): Cancels a workflow run in progress. - [Get workflow analysis (Beta)](https://docs.joinpopp.com/reference/get-workflow-analysis.md): **Beta.** Fields and behaviour may change before general availability. Returns the analysis behind one of a workflow's analysis nodes, with its counts, score bands and requirements. Counts leave out… - [List workflow analysis applications (Beta)](https://docs.joinpopp.com/reference/list-workflow-analysis-applications.md): **Beta.** Fields and behaviour may change before general availability. Lists the applications scored on a workflow analysis node, one row per application with its effective score. Erased candidates… - [Get workflow analysis application (Beta)](https://docs.joinpopp.com/reference/get-workflow-analysis-application.md): **Beta.** Fields and behaviour may change before general availability. Returns one application on a workflow analysis node, with its effective score and the evidence behind it. See [Reading a… - [List workflow analysis application history (Beta)](https://docs.joinpopp.com/reference/list-workflow-analysis-application-history.md): **Beta.** Fields and behaviour may change before general availability. Returns an application's score history on a workflow analysis node, oldest first. Popp records each score when it is produced… - ATS - [List ATS jobs](https://docs.joinpopp.com/reference/list-ats-jobs.md): Returns a paginated list of the authenticated organization's ATS jobs, read live from your connected ATS and annotated with what each job is connected to in Popp (`workflow`, `campaign`, or… - [List ATS job stages](https://docs.joinpopp.com/reference/list-ats-job-stages.md): Returns the interview pipeline stages for a single ATS job, read live from your connected ATS. Discover the `atsJobId` via [`GET /v1/ats/jobs`](/docs/list-ats-jobs). Returns `422` if your connected… - [List ATS rejection reasons](https://docs.joinpopp.com/reference/list-ats-rejection-reasons.md): Returns the rejection reasons configured in the authenticated organization's connected ATS, read live. Use the `atsReasonId` values when configuring workflow behaviour that rejects a candidate in the… - Document Credentials - [Register Document Credential](https://docs.joinpopp.com/reference/create-document-credential.md): Register a credential Popp uses to fetch a candidate's protected documentUrl. Stored at the organization-group level behind your API key. Only one credential is allowed per organization group; if one… - [List Document Credentials](https://docs.joinpopp.com/reference/list-document-credentials.md): List the document-fetch credentials for the organization group behind your API key (paginated). Tokens are never returned. Authenticated with your API key alone. - [Update Document Credential](https://docs.joinpopp.com/reference/update-document-credential.md): Update or rotate a document-fetch credential. Send only the fields you are changing (for example { "token": "..." } to rotate the key). The token is write-only and never returned. A credential in… - [Delete Document Credential](https://docs.joinpopp.com/reference/delete-document-credential.md): Remove a document-fetch credential. A credential in another organization group returns 404. Authenticated with your API key alone. - Custom Fields (Beta) - [Create a custom field (Beta)](https://docs.joinpopp.com/reference/create-custom-field.md): **Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release. Creates a custom field for your organization. The… - [List custom fields (Beta)](https://docs.joinpopp.com/reference/list-custom-fields.md): **Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release. Lists the active custom fields in your organization.… - [Get a custom field (Beta)](https://docs.joinpopp.com/reference/get-custom-field.md): **Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release. Returns a single custom field by id. A field that… - [Update a custom field (Beta)](https://docs.joinpopp.com/reference/update-custom-field.md): **Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release. Updates a custom field's `label`, `hasFixedOptions`,… - [Delete a custom field (Beta)](https://docs.joinpopp.com/reference/delete-custom-field.md): **Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release. Deletes a custom field. **Deletion is permanent and… - Candidates - [Create a candidate](https://docs.joinpopp.com/reference/create-candidate.md): Creates a candidate profile in the caller's organization, or upserts an existing one when the same `externalId` is re-posted. Organization context is taken from the authenticated API key, never from… - [List candidate lists](https://docs.joinpopp.com/reference/list-candidate-lists.md): Returns the candidate lists in the caller's organization, most recently created first. Paginated with `limit` + `nextToken`, and filterable by `title` and/or `externalId`. To fetch a single list by… - [Create a candidate list](https://docs.joinpopp.com/reference/create-candidate-list.md): Creates an empty candidate list in the caller's organization. `title` is required; `description`, `externalId` and `owner` are optional. `externalId` must be unique within the organization. `owner`… - [Get a candidate list](https://docs.joinpopp.com/reference/get-candidate-list.md): Returns a candidate list with a page of its members. Members are paginated with `limit` + `nextToken`; each member includes the candidate profile id, external id (when available), name, email, title,… - [Update a candidate list](https://docs.joinpopp.com/reference/update-candidate-list.md): Updates a candidate list's `title`, `description`, `owner` and/or `externalId`. At least one field must be provided; pass `description: null` to clear it. Pass `externalId` to set or change the… - [Delete a candidate list](https://docs.joinpopp.com/reference/delete-candidate-list.md): Deletes a candidate list and all of its memberships. Returns 204 on success and 404 when the list is not found in the caller's organization. - [Add candidates to a list](https://docs.joinpopp.com/reference/add-candidates-to-list.md): Adds one or more candidate profiles to a list, addressed by profile id (`candidateIds`) and/or external id (`candidateProfileExternalIds`). Candidates already on the list are skipped, so the call is… - [Remove candidates from a list](https://docs.joinpopp.com/reference/remove-candidates-from-list.md): Removes one or more candidate profiles from a list, addressed by profile id (`candidateIds`) and/or external id (`candidateProfileExternalIds`). Candidates not on the list are ignored. Returns 204 on… - [Get a candidate list by external ID](https://docs.joinpopp.com/reference/get-candidate-list-by-external-id.md): Returns the candidate list in the caller's organization with the given external ID, together with a page of its members. Members are paginated with `limit` + `nextToken`. Returns 404 when no list… - [Update a candidate list by external ID](https://docs.joinpopp.com/reference/update-candidate-list-by-external-id.md): Updates the candidate list with the given external ID. Updates `title`, `description`, `owner` and/or `externalId`; at least one field must be provided; pass `description: null` to clear it. Pass… - [Delete a candidate list by external ID](https://docs.joinpopp.com/reference/delete-candidate-list-by-external-id.md): Deletes the candidate list with the given external ID and all of its memberships. Returns 204 on success and 404 when no list matches in the caller's organization. - [Add candidates to a list by external ID](https://docs.joinpopp.com/reference/add-candidates-to-list-by-external-id.md): Adds one or more candidate profiles to the list with the given external ID, addressed by profile id (`candidateIds`) and/or external id (`candidateProfileExternalIds`). Candidates already on the list… - [Remove candidates from a list by external ID](https://docs.joinpopp.com/reference/remove-candidates-from-list-by-external-id.md): Removes one or more candidate profiles from the list with the given external ID, addressed by profile id (`candidateIds`) and/or external id (`candidateProfileExternalIds`). Candidates not on the… - [Update a candidate](https://docs.joinpopp.com/reference/update-candidate.md): Partially updates an existing candidate profile. Send only the fields you want to change: omitting a field leaves the stored value alone, while sending `null` clears it. This endpoint never creates —… - [Update a candidate by external ID](https://docs.joinpopp.com/reference/update-candidate-by-external-id.md): Partially updates an existing candidate profile, addressed by the caller's own identifier rather than Popp's. Behaves exactly like `PATCH /v1/candidates/{id}`: send only the fields you want to change… - [Get a candidate](https://docs.joinpopp.com/reference/get-candidate.md): Returns a candidate profile by its Popp id. Organization context is taken from the authenticated API key, never from the path. A candidate that does not exist and one that belongs to a different… - [Get a candidate by external ID](https://docs.joinpopp.com/reference/get-candidate-by-external-id.md): Returns a candidate profile addressed by the caller's own identifier. The lookup is scoped to the authenticated organization group, so an external id in use by another tenant is never reachable and… - [Delete a candidate](https://docs.joinpopp.com/reference/delete-candidate.md): Permanently deletes the candidate with this Popp id and everything held about them: profile, notes, list memberships, attachments, every CV version, the screening answers from each ATS application,… - [Delete a candidate by external ID](https://docs.joinpopp.com/reference/delete-candidate-by-external-id.md): As `DELETE /v1/candidates/{id}`, addressed by your own external identifier. - [Delete candidates by email](https://docs.joinpopp.com/reference/delete-candidate-by-email.md): As `DELETE /v1/candidates/{id}`, addressed by email. An address can match several candidates; every match in your organization is deleted and the response lists their ids. - [Delete candidates by phone number](https://docs.joinpopp.com/reference/delete-candidate-by-phone-number.md): As `DELETE /v1/candidates/{id}`, addressed by phone number. A number can match several candidates; every match in your organization is deleted and the response lists their ids. - [List a candidate's notes](https://docs.joinpopp.com/reference/list-candidate-notes.md): Every note held about this candidate, newest first: notes added through this API and notes synced from your ATS. Notes are free text written by a recruiter and are searchable — they feed the same… - [List a candidate's notes by external ID](https://docs.joinpopp.com/reference/list-candidate-notes-by-external-id.md): Every note held about this candidate, newest first: notes added through this API and notes synced from your ATS. Notes are free text written by a recruiter and are searchable — they feed the same… - [Add a note to a candidate](https://docs.joinpopp.com/reference/create-candidate-note.md): Records a note against the candidate. Notes are free text and searchable — they feed the same index as the candidate's CV, so the candidate becomes findable on words in the note shortly afterwards.… - [Add a note to a candidate by external ID](https://docs.joinpopp.com/reference/create-candidate-note-by-external-id.md): Records a note against the candidate. Notes are free text and searchable — they feed the same index as the candidate's CV, so the candidate becomes findable on words in the note shortly afterwards.… - [Update a candidate note](https://docs.joinpopp.com/reference/update-candidate-note.md): Replaces the content of a note you added. The candidate is re-indexed, so search reflects the new wording shortly afterwards. Notes synced from your ATS cannot be edited here — edit them in your ATS,… - [Delete a candidate note](https://docs.joinpopp.com/reference/delete-candidate-note.md): Removes a note you added. The candidate is re-indexed, so search stops matching the note's words shortly afterwards — and when it was their last note, the notes text is cleared from search entirely.… - [Re-parse a candidate CV](https://docs.joinpopp.com/reference/reparse-candidate-cv.md): Parses the candidate's stored CV again and re-indexes the candidate, even when the document is unchanged. Use it when parsing failed or should be refreshed. Allowed in any status. Returns 202 once… - [Re-parse a candidate CV by external ID](https://docs.joinpopp.com/reference/reparse-candidate-cv-by-external-id.md): Addressed by the caller's own identifier. Parses the candidate's stored CV again and re-indexes the candidate, even when the document is unchanged. Use it when parsing failed or should be refreshed.… - [Remove a candidate CV](https://docs.joinpopp.com/reference/remove-candidate-document.md): Removes the candidate's CV without deleting the candidate. Every stored version of the document is deleted, the CV-extracted values (the fromCv fields, jobs, education and the like) are cleared, and… - [Remove a candidate CV by external ID](https://docs.joinpopp.com/reference/remove-candidate-document-by-external-id.md): Addressed by the caller's own identifier. Removes the candidate's CV without deleting the candidate. Every stored version of the document is deleted, the CV-extracted values (the fromCv fields, jobs,… - Tags - [List tags](https://docs.joinpopp.com/reference/list-tags.md): Returns the tag catalog for the caller's organization, sorted by tag. This is the vocabulary the candidate tag filter offers. Paginated with `limit` + `nextToken`. Pass `tag` to look up a single tag… - [Delete a tag](https://docs.joinpopp.com/reference/delete-tag.md): Removes a tag from the catalog, so it no longer appears in the candidate tag filter. Candidates are not changed: any candidate carrying the tag keeps it, and the tag returns to the catalog the next…