TalkPush Labels API API

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


    With 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.

    '
  version: '2.0'
  title: Talkpush Agents API Labels API API
  contact:
    email: admin@talkpush.com
servers:
- url: https://company_subdomain.talkpush.com/api/talkpush_services
tags:
- name: Labels API
  description: 'Collection of endpoints related to candidate labels. Labels are simple, company-wide tags that recruiters use to flag and filter candidates (for example: "Priority", "Referral", "Needs Review"). The same labels are visible in the Talkpush UI; anything added via the API immediately appears in the UI and on the candidate''s `labels` field returned by the Leads API.'
paths:
  /company/labels:
    get:
      tags:
      - Labels API
      summary: List company labels
      description: '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.'
      parameters:
      - name: api_key
        in: query
        description: The API key provided for your application.
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: Case-insensitive partial-match filter on the label name. Must be a string; arrays or other types return 400.
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Page number (1-based). Defaults to 1.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Page size. Defaults to 25, capped at 100.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: Labels were returned successfully. The response headers `X-Total-Count` and `X-Page-Count` describe the full result set.
          headers:
            X-Total-Count:
              description: Total number of labels matching the query (across all pages).
              schema:
                type: integer
            X-Page-Count:
              description: Total number of pages available given the current `per_page`.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/labels_list_response'
        '400':
          description: Bad request — for example, `name` was sent as something other than a string.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/label_bad_request_error'
        '401':
          description: Missing, invalid, or inactive API key.
        '500':
          description: Internal server error; the response may include an exception message.
    post:
      tags:
      - Labels API
      summary: Create a label
      description: '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.'
      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/label_create_request'
            examples:
              simple:
                summary: Create a label called "Manager Approved"
                value:
                  label:
                    name: Manager Approved
      responses:
        '201':
          description: Label created. The body contains the new label under `label`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/label_single_response'
        '400':
          description: Bad request — `label.name` was missing or was not a string.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/label_bad_request_error'
        '401':
          description: Missing, invalid, or inactive API key.
        '409':
          description: A label with this name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/label_conflict_error'
        '422':
          description: Validation error — for example, the name contains a forbidden character (`,`, `#` or `?`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/label_validation_error'
        '500':
          description: Internal server error; the response may include an exception message.
components:
  schemas:
    label_conflict_error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          example: conflict
        message:
          type: string
          example: A label with name Priority already exists.
    label_validation_error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          example: unprocessable_entity
        message:
          type: string
          example: Name is invalid
    label:
      type: object
      description: A company-wide candidate label.
      properties:
        id:
          type: integer
          description: Database id of the label.
        name:
          type: string
          description: Display name; unique within the company.
        created_at:
          type: string
          format: date-time
          description: When the label was created.
        updated_at:
          type: string
          format: date-time
          description: When the label was last updated.
      required:
      - id
      - name
      - created_at
      - updated_at
    label_create_request:
      type: object
      required:
      - label
      properties:
        label:
          type: object
          required:
          - name
          properties:
            name:
              type: string
              description: Display name. Trimmed of surrounding whitespace. Must be unique within the company and cannot contain `,`, `#` or `?`.
    label_bad_request_error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          example: bad_request
        message:
          type: string
          example: Parameter label.name is required.
    label_single_response:
      type: object
      required:
      - label
      properties:
        label:
          $ref: '#/components/schemas/label'
    labels_list_response:
      type: object
      required:
      - labels
      properties:
        labels:
          type: array
          items:
            $ref: '#/components/schemas/label'