---
updatedAt: 2026-05-11T21:49:49.000Z
agentTools:
  projectIndex: https://talkpush-apidocs.readme.io/llms.txt
---

# Create a label

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.

# 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": "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": {
      "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}`.\n\n**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).\n\n**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."
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://company_subdomain.talkpush.com/api/talkpush_services"
    }
  ],
  "components": {
    "schemas": {
      "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_single_response": {
        "type": "object",
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "$ref": "#/components/schemas/label"
          }
        }
      },
      "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_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"
          }
        }
      }
    }
  }
}
```