---
updatedAt: 2026-04-21T22:56:43.000Z
agentTools:
  projectIndex: https://talkpush-apidocs.readme.io/llms.txt
---

# List all candidate attribute definitions

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`).

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "<b>Production Base URL to be used during implementation:</b> {your company workspace subdomain}.talkpush.com/api/talkpush_services\n\nWith the Talkpush APIs you can instantly plug your lead source into out platform to enjoy the benefits of Talkpush. You can also synch your <b> existing HR / Recruitment technology stack </b> with your Talkpush account. To be able to use our API you will need pass an api key as a parameter for each API call.  In case you do not know your current API key you can contact our support team at cs@talkpush.com.\n",
    "version": "2.0",
    "title": "Talkpush API",
    "contact": {
      "email": "admin@talkpush.com"
    }
  },
  "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.\n\nEach 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."
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://company_subdomain.talkpush.com/api/talkpush_services"
    }
  ],
  "components": {
    "schemas": {
      "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",
            "nullable": true,
            "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_attributes_list_response": {
        "type": "object",
        "properties": {
          "candidate_attributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/candidate_attribute"
            }
          }
        },
        "required": [
          "candidate_attributes"
        ]
      }
    }
  }
}
```