---
title: "Add people to a list"
method: POST
path: "/api/v1/lists/{id}/members"
tags: ["Lists"]
---

# Add people to a list

`POST /api/v1/lists/{id}/members`

## Request

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

Adds people to a list. Adding is idempotent — person IDs already on the list are ignored and duplicates within `personIds` are collapsed, so the call still returns `200`. A list holds at most 12,000 members; a request that would take it past that returns `422`, as does a person ID that does not belong to your agency (including one that has since been merged into another person). Note: the list `entityType` (candidate or contact) is **not** validated against the people you add — any person in your agency can be added to any list.

## Path parameters

- `id` string, uuid, required: List ID

## Request body

- object
  - `personIds` string[], required: Person IDs to add or remove (max 100 per request)

## Response `200`

Members added

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, uuid, required: List ID
    - `name` string, required: List name
    - `entityType` 'candidate' | 'contact', required: What the list holds
    - `visibility` 'public' | 'team' | 'private', required: Who can see the list
    - `editable` boolean, required: Whether users who can see the list may change its members
    - `owner` object, required: The user who owns the list
      - `id` string, uuid, required
      - `name` string, required: "Deleted user" when the owner has been deleted
      - `deleted` boolean, required
    - `memberCount` integer, required: Number of people currently on the list
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required: When the list itself was last changed — renamed, re-shared, ownership moved. Adding or removing members does NOT move it; page `GET /lists/{id}/members` and read `addedAt` to detect membership changes

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `403`: Forbidden — the Lists feature is switched off for this environment, or the list is visible to you but you may not change its members
- `404`: The list does not exist, belongs to another agency, or is not visible to you
- `415`: The request carried a body without `Content-Type: application/json`
- `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
- `501`: Endpoint is disabled in this environment (feature-flagged). Not a routing error — do not retry.

## Changes

- **2026-10-03** `cd4bc8bbd95e`: 1 breaking, 5 warning, 4 info
  - removed the required property `data/ownerId` from the response with the `200` status
  - added the new `candidate` enum value to the `data/entityType` response property for the response status `200`
  - added the new `contact` enum value to the `data/entityType` response property for the response status `200`
  - added the new `private` enum value to the `data/visibility` response property for the response status `200`
  - …6 more
- **2026-09-29** `d7ef7f970d5b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/lists/:id/members/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)