---
title: "Add items to list"
method: POST
path: "/v2/lists/{id}/items"
tags: ["Lists"]
---

# Add items to list

`POST /v2/lists/{id}/items`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/lists/{id}/items`
- Auth: HTTP bearer

Add people or companies to a list. Use this to populate your lists with contacts or accounts. Provide an array of identifiers (LinkedIn URLs, company domains, or Village IDs, the `graph_id` other tools return). Each identifier is resolved and added to the list. Returns detailed results for each item: successful additions include the created item, failures include error codes and messages. Duplicates are detected and reported.

## Path parameters

- `id` string, required: List ID

## Request body

- AddItemsRequest: Request body for adding items to a list
  - `items` object[], required: Array of items to add to the list
    - `identifier` string, required: Identifier for the entity (LinkedIn URL, domain, email, or Village ID, the `graph_id` other tools return)
    - `type` 'people' | 'company': Entity type hint (optional, will be inferred from identifier if not provided)

## Response `200`

Items processed

- object
  - `data` AddItemsResponse, required: Response after adding items to a list
    - `results` AddItemResult[], required: Results for each item
      - `identifier` string, required: Original identifier provided
      - `item` object: Created item (if successful)
        - `id` number: Unique item identifier. Absent when the list was read by its public identifier — the id is a handle for mutating the row, and a public reader has nothing to mutate.
        - `graph_id` string, required: Graph database identifier
        - `type` 'people' | 'company', required: Entity type
        - `data` object, required: Entity data (profile information)
        - `screening` object, nullable, required: Autopilot screening result for this item, or null if the list has not been screened. Present so reading a screened list surfaces its scores. There is no stored pass/fail verdict — compare `score` against your own threshold.
          - `score` number, nullable, required: Autopilot overall_match_score (0–1), null if not yet scored
          - `match_brief` union: Short human-readable summary of WHY this item matched. Only on public-identifier reads.
            - string
            - object
              - …
            - unknown
          - `criteria_scores` object[]: Per-criterion scores, aligned with the list-level `criteria`. Only on public-identifier reads.
            - `criterion` string, required
            - `score` number, nullable, required
        - `created_at` string: ISO 8601 creation timestamp
      - `error` object: Error details (if failed)
        - `code` 'DUPLICATE' | 'NOT_FOUND' | 'INVALID_IDENTIFIER' | 'INTERNAL_ERROR', required: Error code
        - `message` string, required: Human-readable error message
    - `summary` object, required
      - `total` number, required: Total items processed
      - `added` number, required: Successfully added items
      - `failed` number, required: Failed items
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `404`: List not found

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)