---
title: "List person custom attribute definitions"
method: GET
path: "/api/v1/people/custom-attributes"
tags: ["Custom Attributes"]
---

# List person custom attribute definitions

`GET /api/v1/people/custom-attributes`

## Request

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

Returns the custom attribute **definitions** (schema) configured for person records on this agency, including selectable options for dropdown-type attributes. `options` is deprecated: it lists every option unpaged — use `GET /api/v1/people/custom-attributes/{id}/options` to page and search them.

Use this to discover which custom fields exist and what values are valid before reading or writing attribute data on person records.

## Query parameters

- `page` integer: Page number (1-indexed)
- `pageSize` integer: Items per page (max 100)
- `perPage` integer: Alias for pageSize

## Response `200`

Paginated list of person custom attribute definitions

- 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: Deprecated: every option of the attribute, unpaged, so it can be very large. Use `GET …/custom-attributes/{id}/options` to page and search them. 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
  - `pagination` object, required
    - `page` integer, required: Current page number
    - `pageSize` integer, required: Items per page
    - `total` integer, required: Total matching items
    - `totalPages` integer, required: Total number of pages

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `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-08** `d03098466694`: 1 info
  - response property `data/items/options` deprecated
- **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/people/custom-attributes/get.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)