# Talkpush API Docs Documentation

> Documentation for Talkpush API Docs

## Guides
- [Getting Started with Talkpush API Docs](https://talkpush-apidocs.readme.io/docs/getting-started.md): With the Talkpush APIs you can instantly plug your lead source into out platform to enjoy the benefits of Talkpush.     You can also synchronize your <b> existing HR / Recruitment technology stack </b> with your Talkpush account.     To be able to use our API you will need to pass an API Key as a parameter for each API call.

## API Reference
- [Retrieve a list of leads matching your search criterias](https://talkpush-apidocs.readme.io/reference/get_campaign-invitations.md): This API endpoint will enable you to search through your lead database programatically  with the same criterias than you would use on the recruiter's leads page.  You can execute 2 kinds of search:    * Use the query parameter which is equivalent to typing your search query in a search bar.    * Use a combination of parameter to execute an advanced search
- [Update a lead's details](https://talkpush-apidocs.readme.io/reference/patch_campaign-invitations-id.md): Updates the details of an existing lead. In addition to the fields on the candidate, this endpoint accepts an optional `candidate.labels` object to add or remove labels on the candidate in a single request.  **Labels payload (optional):** When `candidate.labels` is provided, it MUST include both an `add` and a `remove` array (send an empty array if you don't need that side). All names referenced in `add`/`remove` must already exist as company labels (create them first via `POST /company/labels`); if any are missing the whole request fails with 422 and nothing is changed. Names that don't exist as labels yet cause the whole request to fail with **422**, and no labels are modified — the change is all-or-nothing.
- [Create a new lead](https://talkpush-apidocs.readme.io/reference/post_campaigns-id-campaign-invitations.md): This endpoint can be used to insert a new lead in the campaign given in url
- [Complete the interview for a candidate aplication](https://talkpush-apidocs.readme.io/reference/post_campaign-invitations-id-interview.md): With this endpoint a candidate can complete the campaign's interview. <b> DISCLAIMER </b> - Only text, short_text and multiple choice question types supported. No audio or image question type supported.
- [Create a comment for a lead](https://talkpush-apidocs.readme.io/reference/post_campaign-invitations-id-comments.md): With this endpoint you can add comments to the lead's profile (the campaign invitation).
- [Change lead's status](https://talkpush-apidocs.readme.io/reference/put_campaign-invitations-id-status.md): Update the lead status
- [Move a lead to a different campaign](https://talkpush-apidocs.readme.io/reference/put_campaign-invitations-id-move.md): With this endpoint you can move a lead (the campaign invitation) between different campaigns. E.g. a candidate applied for Front end developer but her profile actually suits the fullstack developer position better, in that case you might want to move the application to the fullstack developer campaign.  Applications cannot be moved to the inbox folder of another campaign.
- [Reassign a lead to another user](https://talkpush-apidocs.readme.io/reference/put_campaign-invitations-id-reassign.md): Inside the Talkpush CRM Leads can be assigned to recruiters, this allows user to easily find their leads. With this endpoint you can change the assigned recruiter of a lead.
- [Attach a document to a lead](https://talkpush-apidocs.readme.io/reference/put_campaign-invitations-id-documents.md): With this endpoint you can attach a document to a lead. A document tag Id or Name are needed to attach the file to a lead.
- [Retrieve all the available Quick Reply templates](https://talkpush-apidocs.readme.io/reference/get_messaging-quick-replies.md): This endpoint let's you retrieve all the available Quick Reply templates, view their content, title and the ID which you will require in order to send a message via the /messaging endpoint.
- [Send a quick reply template to a lead.](https://talkpush-apidocs.readme.io/reference/post_messaging-messages.md): This endpoint lets you send a quick reply template to a given lead, via a determined channel. The ID of a quick reply template can be retrieved either inside the CRM's Quick Reply Management Screen or via the /messaging/quick_replies endpoint specified below.
- [Retrieve all active campaigns of the account](https://talkpush-apidocs.readme.io/reference/get_campaigns.md): This endpoint returns a list of all the active campaigns in the company account. The campaigns can be filtered by type parameter (optional), **if no type is defined, by the default, the result will include ONLY job_application type campaigns**.
- [Create a new campaign inside your Talkpush account](https://talkpush-apidocs.readme.io/reference/post_campaigns.md): This endpoint lets you create a new campaign inside Talkpush. Not all the information required to set up a fully operational campaign can be provided via the API.  Permission settings, questions, message, smart filters and notifications need to set up from the campaign settings inside the CRM.  A common use case for this endpoint would be the automatic creation of a campaign inside Talkpush when a user creates a job requisiton inside an integrated ATS.
- [Retrieve all archive campaigns of the account](https://talkpush-apidocs.readme.io/reference/get_campaigns-archive.md): This endpoint returns a list with all the archive campaigns in the company account.
- [Retrieve details of active campaigns that match the search criteria](https://talkpush-apidocs.readme.io/reference/get_campaigns-search-criteria.md): This endpoint returns a list of active campaigns that match the search criteria in the company account.
- [Retrieve details of a specific active campaign](https://talkpush-apidocs.readme.io/reference/get_campaigns-id.md): This endpoint returns a specific campaigns details in the company account.
- [Update a campaign inside your Talkpush account](https://talkpush-apidocs.readme.io/reference/put_campaigns-id.md): This endpoint lets you update an exixting campaign inside Talkpush. Not all the information required to update the campaign.  Permission settings, questions, message, smart filters and notifications need to be updated from the campaign settings inside the CRM.
- [Get questions for a specific campaign](https://talkpush-apidocs.readme.io/reference/get_campaigns-id-questions.md): This endpoint let's you retrieve all the questions that are associated to a campaign for which you provide the ID in the path. <b> DISCLAIMER </b> - Only text, short_text and multiple choice types supported. No audio or image type question supported.
- [Retrieve all the folders that are associated to a campaign](https://talkpush-apidocs.readme.io/reference/get_campaigns-id-folders.md): This endpoint let's you see what folders are associated to the campaign for which you provide the ID in the path
- [Archive an existing campaign](https://talkpush-apidocs.readme.io/reference/put_campaigns-id-archive.md): This endpoint let's you archive a campaign for which you provide the ID in the path
- [Activate an archived campaign](https://talkpush-apidocs.readme.io/reference/put_campaigns-id-activate.md): This endpoint let's you activate a archived campaign for which you provide the ID in the path
- [Associate a campaign with a custom folder](https://talkpush-apidocs.readme.io/reference/post_campaigns-campaign-id-folders-folder-id.md): In order for custom folders to become available in a given campaign they need to be associated with the campaign. This is not necessary for custom folders that are enabled as default folders, which are by default associated to all campaigns.
- [Retrieve all the available folders on the company account](https://talkpush-apidocs.readme.io/reference/get_company-folders.md): This endpoint let's you retrieve all the available folders on the company account and shows whether these are default folders. This is useful for example if you want to display the them inside your ATS.
- [Create custom folders](https://talkpush-apidocs.readme.io/reference/post_company-folders.md): This endpoint let's you create custom folders in the company account. A common scenario for this endpoint would be to create a custom folder whenever you create a new recruitment process step inside the ATS.
- [Retrieve all the available document tags(templates) on the company account](https://talkpush-apidocs.readme.io/reference/get_document-tags.md): This endpoint let's you retrieve all the available document tags(templates) on the company account.
- [Retrieve a list of calls within a date range](https://talkpush-apidocs.readme.io/reference/get_calls.md): This endpoint returns a paginated list of calls within the specified date range. Each call record includes the associated app_id. The start_date and end_date parameters are required and must be in DD-MM-YYYY format.
- [List all candidate attribute definitions](https://talkpush-apidocs.readme.io/reference/get_company-candidate-attributes.md): Returns every attribute definition for the company, including default (system) and custom attributes, ordered by `name`. Use this to drive integrations and to discover keys for the leads `others` payload.  Each item includes type, suggested values, visibility flags, and whether the attribute is a default (built-in) field (`default: true`) or a custom one (`default: false`).
- [Create a custom candidate attribute](https://talkpush-apidocs.readme.io/reference/post_company-candidate-attributes.md): Creates a new **custom** attribute definition. It becomes available in the UI immediately and is writable on leads through the `others` field using the persisted key (custom keys are stored with an `others.` prefix where applicable).  **Duplicate prevention:** If the normalized `key` already exists for an attribute, the API returns **409 Conflict** (not a second record).  **Required fields:** `name` and `key` (see request schema). `data_type` defaults to `text` when omitted.
- [Retrieve a list of agents](https://talkpush-apidocs.readme.io/reference/get_agents.md): Returns a paginated list of AI agents configured in the company account, ordered by most recently updated. Supports optional filtering by category, provider, and active status.
- [Retrieve details of a specific agent](https://talkpush-apidocs.readme.io/reference/get_agents-id.md): Returns the full detail of a single agent, including its prompt, provider info, linked question set, and the complete data extractions configuration.
- [Update an existing agent](https://talkpush-apidocs.readme.io/reference/put_agents-id.md): Updates an agent's configuration. All fields are optional — only the fields provided will be changed. **Note:** if `data_extractions` is included, it **replaces** the existing extractions entirely (not a partial merge). The same applies to `prompt`.
- [Delete an agent](https://talkpush-apidocs.readme.io/reference/delete_agents-id.md): Permanently deletes the agent identified by `id`. On success, returns HTTP 204 with no response body.
- [Retrieve a list of calls for a specific agent](https://talkpush-apidocs.readme.io/reference/get_agents-agent-id-calls.md): Returns a paginated list of call records handled by the given agent, ordered by most recent first. Each record includes the associated application (candidate / campaign invitation) context, extracted data, interview insights, transcript, and a link to the call recording when available.  Optional filters: - `status`: filter by call status. - `start_date` + `end_date`: filter by creation date range. Both parameters must be provided together. Any format accepted by `Time.zone.parse` is supported (e.g. `2026-04-01`, `2026-04-01T00:00:00Z`).
- [Retrieve the changelog for a specific agent](https://talkpush-apidocs.readme.io/reference/get_agents-agent-id-changelog.md): Returns a paginated list of audit log entries for the given agent, ordered by most recent first. Each entry describes a single create, update, or destroy event — who made the change, when, and what fields were affected.  For `created` entries the `changes` array is always empty (the initial state is not diffed). For `updated` entries each item in `changes` names the API field that changed and includes both the previous and new value.  **Possible `field` values inside a change entry:** - `agent_name` — display name of the agent (stored as `title`) - `description` — short description - `prompt` — agent prompt, rendered as a plain-text string - `data_extractions` — array of `{ "candidate_attribute": "<key>" }` objects - `category` — category enum key (e.g. `talkscore_interview`, `phone_calls`, `onsite_interview`, `event_invitation`, `passive_candidate_outreach`, `status_update`, `reminder`) - `provider` — provider key (e.g. `elevenlabs`, `vapi`) - `provider_agent_id` — provider-side agent identifier - `question_set_id` — ID of the linked question set - `is_active` — boolean active/inactive flag  **`changed_by` values:** - Manager email address when the change was made from the Talkpush CRM - `"TalkPush API"` when the change was made via the API
- [Create a new agent](https://talkpush-apidocs.readme.io/reference/post_agents.md): Creates a new AI agent configuration. On success, returns HTTP 201 with the newly created agent details.  The `data_extractions` field in the request uses the candidate attribute **key** string (e.g. `"english_level"`) — unlike the update endpoint, which uses `{ "id": "..." }`. The response returns an array of extraction objects (not the keyed map returned by the show/update endpoints).
- [List company labels](https://talkpush-apidocs.readme.io/reference/get_company-labels.md): Returns labels configured for the company account. Results are paginated and can be filtered by name. The system-reserved `Deleted` label is excluded.  **Pagination:** Use `page` and `per_page` (default 25, max 100). The response includes the headers `X-Total-Count` (total matching labels) and `X-Page-Count` (total number of pages) to make page traversal straightforward.  **Filtering:** Use `name` for a case-insensitive partial-match filter — handy for companies with thousands of labels.
- [Create a label](https://talkpush-apidocs.readme.io/reference/post_company-labels.md): Creates a new label for the company. The label becomes available in the UI immediately and can be assigned to candidates via `PATCH /campaign_invitations/{id}`.  **Duplicate prevention:** If a label with the same name already exists, the API returns **409 Conflict**. This is enforced both before saving and after, so a concurrent create with the same name still maps cleanly to 409 (never a 422 validation error).  **Name rules:** Names are trimmed of surrounding whitespace. Names containing `,`, `#` or `?` are rejected with 422.
- [List message templates](https://talkpush-apidocs.readme.io/reference/get_messaging-templates.md): Returns all Message Templates for the company, excluding system-internal `StatusReason` sub-type templates.  Content is always returned in Handlebars format (`{{token_name}}`), even when the underlying template was created through the UI using the legacy DraftJS editor.  **Filtering:** Use `name` (case-insensitive partial match), `type` (`email`, `sms`, `whatsapp`, `messenger`, or `calendar`), and `category` (exact match) to narrow results.  **Pagination:** Use `page` and `per_page` (default 25, max 100). Response headers `X-Total-Count` and `X-Page-Count` describe the full result set.
- [Create a message template](https://talkpush-apidocs.readme.io/reference/post_messaging-templates.md): Creates a new Message Template for the company. The template is immediately available in the UI and can be referenced by autoflows.  **Content format:** The `content` field must use Handlebars syntax for dynamic tokens, e.g. `Hi {{candidate_name}}, your interview for {{job_title}} is confirmed.` All tokens used in `content` are validated against the company's available tokens (see `GET /messaging/tokens`). Unknown tokens return a **422** with the list of offending token names.  **Type:** Use `email`, `sms`, `whatsapp`, or `messenger`. The `calendar` type is not yet supported via the API.  **Required fields:** `name`, `content`, `type`, `sub_type`, `category`.
- [Update a message template](https://talkpush-apidocs.readme.io/reference/patch_messaging-templates-id.md): Partially updates an existing Message Template. Only the fields provided in the request body are changed; omitted fields are left unchanged.  **Content validation:** If `content` is provided, all Handlebars tokens are re-validated. Unknown tokens return a **422** with the list of offending token names.  **Settings merge:** When `settings` is provided, the new values are merged into the existing settings object. The internal `content_state` key is automatically stripped and never returned.
- [List available message tokens](https://talkpush-apidocs.readme.io/reference/get_messaging-tokens.md): Returns all tokens that can be used inside a Message Template's `content` field. The list includes:  - **System tokens** — built-in reserved words (e.g. `candidate_name`, `job_title`, `scheduler_url`) that are resolved at send time. - **Custom tokens** — company-defined tokens created by your team.  Use the `id` of a token as the Handlebars key in template content: `{{candidate_name}}`, `{{job_title}}`, etc.  **Filtering:** Use `display_name` for a case-insensitive partial-match filter to quickly find the token you need.
- [List movement (shortlist & reject) reasons](https://talkpush-apidocs.readme.io/reference/get_movement-reasons.md): Returns the company's configured **Shortlist Reasons** and **Reject Reasons** — the values recruiters can pick when moving a candidate to a shortlisted or rejected state. Soft-deleted reasons are excluded.  **Filtering:** Use the optional `type` query parameter to narrow the results to a single bucket (`rejected` or `shortlisted`). Omitting it returns both buckets in one response. Any other value returns **422 Unprocessable Entity**.  **Pagination:** Use `page` and `per_page` (default 25, max 100). The response headers `X-Total-Count` (total matching reasons) and `X-Page-Count` (total pages) make page traversal straightforward.
- [List company managers](https://talkpush-apidocs.readme.io/reference/get_managers.md): Returns the active managers (platform users) for the authenticated company. Deactivated managers are excluded. Results are paginated and can be filtered by role and name.  **Pagination:** Use `page` and `per_page` (default 25, max 100). The response headers `X-Total-Count` (total matching managers) and `X-Page-Count` (total pages) make page traversal straightforward.  **Filtering:** Use `role` for an exact-match filter on the manager's resolved role name, and `name` for a case-insensitive partial-match filter on the manager's first/last name. The two filters can be combined.
- [Callback endpoint](https://talkpush-apidocs.readme.io/reference/post_rms-callback.md): This API endpoint will be used to receive callbacks from RMS when a job requisition is created.