> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Add list items > Add persons or companies to a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request. Soft-deleted memberships are restored instead of duplicated. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/lists/{id}/items openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/lists/{id}/items: post: tags: - Lists summary: Add list items description: >- Add persons or companies to a saved list in bulk. Invalid IDs fail individually and do not block other IDs in the same request. Soft-deleted memberships are restored instead of duplicated. operationId: addListItems parameters: - in: path name: id required: true schema: type: string description: List UUID requestBody: content: application/json: schema: $ref: '#/components/schemas/ListItemsMutationRequest' responses: '200': description: List items added content: application/json: schema: $ref: '#/components/schemas/ListItemsAddResponse' example: success: true data: list_id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 list_type: persons added_ids: - ccc33333-dddd-eeee-ffff-000000003333 reactivated_ids: [] already_present_ids: [] failed: - id: 99999999-8888-7777-6666-555555555555 reason: not_found '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: ListItemsMutationRequest: type: object properties: person_ids: type: array items: type: string format: uuid description: >- Person UUIDs to add or remove. Only valid for lists with list_type "persons". company_ids: type: array items: type: string format: uuid description: >- Company UUIDs to add or remove. Only valid for lists with list_type "companies". team_member_id: type: string format: uuid description: >- Team member UUID to attribute as the actor for this mutation. Required for API-key auth (which has no implicit user context). Ignored when using session or OAuth auth. ListItemsAddResponse: type: object properties: success: type: boolean enum: - true data: type: object properties: list_id: type: string format: uuid description: List UUID. list_type: type: string enum: - persons - companies description: Type of entities accepted by this list. added_ids: type: array items: type: string format: uuid description: IDs inserted as new list items. reactivated_ids: type: array items: type: string format: uuid description: IDs whose previously removed list item was restored. already_present_ids: type: array items: type: string format: uuid description: IDs that were already active in the list. failed: type: array items: type: object properties: id: type: string format: uuid description: Person or company UUID. reason: type: string description: >- Why this ID was not processed, such as not_found or wrong_list_type. required: - id - reason description: >- IDs that could not be added. Other valid IDs in the same request are still processed. required: - list_id - list_type - added_ids - reactivated_ids - already_present_ids - failed required: - success - data securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````