List and create candidate (lead) custom attribute definitions at the company level. Definitions appear in the recruiter UI and can be written on leads via the `others` field using the attribute key. Both built-in (`default`) and custom attributes are returned on list.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/talkpush-candidate-attributes-api-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
description: 'Production Base URL to be used during implementation: {your company workspace subdomain}.talkpush.com/api/talkpush_services
With the Talkpush APIs you can instantly plug your lead source into out platform to enjoy the benefits of Talkpush.'
version: '2.0'
title: Talkpush Candidate Attributes API
contact:
email: admin@talkpush.com
servers:
- url: https://company_subdomain.talkpush.com/api/talkpush_services
tags:
- name: Candidate Attributes API
description: List and create candidate (lead) custom attribute definitions at the company level. Definitions appear in the recruiter UI and can be written on leads via the `others` field using the attribute key. Both built-in (`default`) and custom attributes are returned on list.
paths:
/company/candidate_attributes:
get:
tags:
- Candidate Attributes API
summary: List all candidate attribute definitions
description: '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`).'
parameters:
- name: api_key
in: query
description: The API key provided for your application.
required: true
schema:
type: string
responses:
'200':
description: Attribute definitions were returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/candidate_attributes_list_response'
'401':
description: Missing, invalid, or inactive API key.
'500':
description: Internal server error; the response may include an exception message.
operationId: getCompanyCandidateAttributes
x-operation-id-source: derived
post:
tags:
- Candidate Attributes API
summary: Create a custom candidate attribute
description: '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.'
parameters:
- name: api_key
in: query
description: The API key provided for your application.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/candidate_attribute_create_request'
examples:
signingStatus:
summary: Text attribute with suggested values
value:
candidate_attribute:
name: Signing Status
key: signing_status
data_type: text
description: Document signing status
suggested_values:
- pending
- viewed
- completed
- declined
allow_only_suggested_values: true
auto_add_to_all_candidates: false
responses:
'200':
description: The attribute was created successfully. The body contains the full definition under `candidate_attribute`, including `id`.
content:
application/json:
schema:
$ref: '#/components/schemas/candidate_attribute_single_response'
'401':
description: Missing, invalid, or inactive API key.
'409':
description: 'Conflict: an attribute with this key already exists (after key normalization).'
content:
application/json:
schema:
$ref: '#/components/schemas/candidate_attribute_conflict_error'
example:
error: A candidate attribute with this key already exists
'422':
description: 'Validation error. Common cases: missing `name` or `key`, or model validation failures.'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/candidate_attribute_validation_errors'
- type: object
properties:
errors:
type: array
items:
type: string
example:
- Key is required
required:
- errors
'500':
description: Internal server error; the response may include an exception message.
operationId: postCompanyCandidateAttributes
x-operation-id-source: derived
components:
schemas:
candidate_attributes_list_response:
type: object
properties:
candidate_attributes:
type: array
items:
$ref: '#/components/schemas/candidate_attribute'
required:
- candidate_attributes
candidate_attribute:
type: object
description: Single attribute definition as returned by the API (list or create response).
properties:
id:
type: integer
description: Database id of the definition.
name:
type: string
description: Human-readable label shown in the UI.
data_type:
type: string
description: Storage type (e.g. `text`, `number`, `datetime`).
suggested_values:
type: array
items:
type: string
description: Optional preset choices; empty array if none.
description:
type:
- string
- 'null'
description: Optional longer description.
allow_only_suggested_values:
type: boolean
description: When true, values may be restricted to `suggested_values` (UI / validation behavior).
auto_add_to_all_candidates:
type: boolean
description: When true, the field is shared across candidates (auto-attached behavior).
always_show_across_applications:
type: boolean
description: When true, the attribute is shown explicitly across applications.
private:
type: boolean
description: Private visibility flag.
restrict_to_owners:
type: boolean
description: When true, access is limited to owners.
default:
type: boolean
description: True for built-in (default) attributes; false for API-created custom attributes.
required:
- id
- name
- data_type
- suggested_values
- allow_only_suggested_values
- auto_add_to_all_candidates
- always_show_across_applications
- private
- restrict_to_owners
- default
candidate_attribute_conflict_error:
type: object
properties:
error:
type: string
example: A candidate attribute with this key already exists
required:
- error
candidate_attribute_create_request:
type: object
required:
- candidate_attribute
properties:
candidate_attribute:
type: object
required:
- name
- key
properties:
name:
type: string
description: Display name of the attribute.
key:
type: string
description: Stable identifier used for storage and for the leads `others` payload. Must be unique after server-side normalization (duplicate returns 409).
data_type:
type: string
description: Defaults to `text` if omitted.
default: text
description:
type: string
description: Optional description.
suggested_values:
type: array
items:
type: string
description: Optional list of suggested values.
allow_only_suggested_values:
type: boolean
description: Maps to suggestions-only mode when provided.
auto_add_to_all_candidates:
type: boolean
description: Maps to shared / auto-add behavior when provided.
candidate_attribute_single_response:
type: object
required:
- candidate_attribute
properties:
candidate_attribute:
$ref: '#/components/schemas/candidate_attribute'
candidate_attribute_validation_errors:
type: object
properties:
errors:
type: array
items:
type: string
description: Rails `full_messages` when model validation fails.
required:
- errors