# Add List members (/docs/api-reference/add_list_members)

`POST /v1/lists/{list_id}/members` · operation `add_list_members`

Add many Businesses or People to a List and set their private column values in one call: set_list_override include plus set_list_entry_value for each, with one version. Same rules: each must be a Record you can see (adding never grants access), each column this List's. Already on it is fine; values sent overwrite. All or nothing: details.member_index names the first member refused.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `list_id` | string | yes |  |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | yes |  |
| `SMB-Workspace-Id` | string (uuid) | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_version` | integer | yes |  |
| `members` | array of object | yes | Up to 5,000 Businesses (biz_) or People (person_), each once. |
| `members[].id` | string or string | yes |  |
| `members[].values` | object | no | Private values by List column_id: {value_type, value} as set_list_entry_value takes it, or null to clear. |

### Response

**200** Successful authorized response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.list_id` | string | yes |  |
| `data.version` | integer | yes |  |
| `data.members` | integer | yes |  |
| `data.added` | integer | yes | Members this call hand-picked onto the List. |
| `data.updated` | integer | yes | Members already hand-picked; only the values sent changed. |
| `request_id` | string | yes |  |
| `action_receipt` | object | yes |  |
| `action_receipt.receipt_id` | string (uuid) | yes |  |
| `action_receipt.command_id` | string (uuid) | yes |  |
| `action_receipt.operation` | `add_list_members` | yes |  |
| `action_receipt.workspace_id` | string (uuid) | yes |  |
| `idempotent_replay` | boolean | yes |  |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request POST "https://api.smb.co/v1/lists/$LIST_ID/members" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"expected_version":1,"members":[]}'
```