---
title: "Create a company custom attribute definition"
method: POST
path: "/api/v1/companies/custom-attributes"
tags: ["Custom Attributes"]
---

# Create a company custom attribute definition

`POST /api/v1/companies/custom-attributes`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/companies/custom-attributes`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recruitwithatlas/apis/atlas-api/docs/api/v1/companies/custom-attributes/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new agency-wide custom attribute **definition** for company records.

For `options`-type attributes, provide the selectable choices via `options` (in display order) and optionally set `multipleValues` to allow multi-select. The attribute name must be unique per entity type within the agency (exact match, case-sensitive — same as the Atlas app) — a duplicate name returns `409`.

## Request body

- object
  - `name` string, required: Display name. Must be unique per entity type within the agency (exact match, case-sensitive). Leading/trailing whitespace is trimmed.
  - `type` 'options' | 'text_block' | 'text_line' | 'integer' | 'date', required: Data type of the attribute
  - `multipleValues` boolean: When true and `type` is `options`, multiple options can be selected. Only allowed for `options` type. Defaults to false.
  - `options` string[]: Selectable choices, in display order. Required (at least one value) when `type` is `options`; not allowed otherwise. Values must be unique (case-insensitive).

## Response `201`

Created company custom attribute definition

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, uuid, required: Attribute identifier. Use this when reading/writing values.
    - `name` string, required: Display name
    - `description` string, nullable, required: Optional description of the attribute's purpose
    - `type` 'options' | 'text_block' | 'text_line' | 'number_input' | 'integer' | 'date', required: Data type of the attribute
    - `multipleValues` boolean, required: When true and `type` is `options`, multiple options can be selected
    - `recordType` 'both' | 'contract' | 'permanent': Placement attributes only — which placement kinds the attribute applies to
    - `options` object[], required: Selectable choices. Populated when type is `options`, empty array otherwise.
      - `id` string, uuid, required: Option identifier. Use this when setting a value.
      - `value` string, required: Display label
      - `position` integer, required: Sort order (ascending)
    - `createdAt` string, date-time, nullable, required: ISO 8601 timestamp when the attribute was created
    - `updatedAt` string, date-time, nullable, required: ISO 8601 timestamp when the attribute was last updated

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `409`: Conflict - the request cannot be fulfilled because of a conflict with the current state of the resource
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error

## Changes

- **2026-10-03** `cd4bc8bbd95e`: 1 info
  - added the optional property `error` to the response with the `422` status

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/companies/custom-attributes/post.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/158ee454751c?raw)