> ## Documentation Index > Fetch the complete documentation index at: https://docs.loice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Save lead-search results to a list > Adds people to an existing list (`listId`) or to a new one created in the same call (`newList`). People are REFERENCES the workspace already holds: `runResultIds` from `GET /api/v1/lead-search/runs/{runId}`. A person already in the list is not added twice; a person on a do-not-contact list is withheld and counted in `suppressed`. Send an `Idempotency-Key` so a retried “create and add” reuses the list it created. #### Billing Free — this endpoint does not consume points. ## OpenAPI ````yaml /openapi.json post /api/v1/lead-lists/add openapi: 3.1.0 info: title: Loice API version: v1 description: >- The Loice API finds and verifies professional contact data. Every capability is exposed here, key-authenticated and rate-limited; the web app is a client of the same platform. **Authentication** — pass your workspace API key on every request (except the API description) as `Authorization: Bearer loice_sk_…`. Keys are created under Settings → API Keys. **Billing** — operations are billed in points against your workspace balance. Each operation below states when the charge applies. The current cost of every operation is shown in the app under [Settings → Billing](https://app.loice.ai/settings/account?tab=billing) and in the live API description, `GET /api/v1/openapi.json`. Calls that fail because of a system or provider error (timeouts, upstream failures, our defects) are not billed, and rate-limited calls are rejected before any billable work. Check headroom with `GET /api/v1/points`. Where an operation documents an `Idempotency-Key` header, send one to retry safely: a repeated request returns the original outcome and is not charged again. **Errors** — every non-200 response has the shape `{ "error": { "message": "…" } }`. Operations whose error responses document an `error.code` also return that machine-readable code beside the message; branch on the code, not the text. servers: - url: https://app.loice.ai security: [] paths: /api/v1/lead-lists/add: post: summary: Save lead-search results to a list description: >- Adds people to an existing list (`listId`) or to a new one created in the same call (`newList`). People are REFERENCES the workspace already holds: `runResultIds` from `GET /api/v1/lead-search/runs/{runId}`. A person already in the list is not added twice; a person on a do-not-contact list is withheld and counted in `suppressed`. Send an `Idempotency-Key` so a retried “create and add” reuses the list it created. #### Billing Free — this endpoint does not consume points. requestBody: required: true content: application/json: schema: type: object properties: listId: type: string minLength: 1 maxLength: 64 newList: type: object properties: name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 1000 required: - name runResultIds: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 1000 lookupIds: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 1000 bulkRowIds: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 1000 bulkBatchId: type: string minLength: 1 maxLength: 64 example: newList: name: Fintech CFOs runResultIds: - cmf3x0v2b0002abcd responses: '200': description: What was added. content: application/json: schema: type: object properties: data: type: object properties: listId: type: string listName: type: string listCreated: type: boolean added: type: integer alreadyInList: type: integer suppressed: type: integer description: >- People withheld by a do-not-contact entry; nothing about them is stored. skipped: type: integer description: >- References not added: unknown, of another workspace, erased or expired, or with nothing to identify the person. `skippedReasons` splits them. skippedReasons: type: object properties: unavailable: type: integer description: Unknown, of another workspace, erased or expired. noIdentity: type: integer description: >- Nothing identifies the person: no LinkedIn profile, no address, no name and company. required: - unavailable - noIdentity description: >- Why each skipped reference was not added; sums to `skipped`. merged: type: integer description: >- Contacts this add merged into others: it proved they are one person (a shared LinkedIn profile or address, or — for people found on a company website with no profile — the same name at the same company). autoSyncRunId: type: - string - 'null' required: - listId - listName - listCreated - added - alreadyInList - suppressed - skipped - skippedReasons - merged - autoSyncRunId required: - data example: data: listId: cmf3x0v2b0001abcd listName: Fintech CFOs listCreated: true added: 1 alreadyInList: 0 suppressed: 0 skipped: 0 autoSyncRunId: null '400': description: >- `validation_error`: the body is invalid (the message names the problem). content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '401': description: >- API key missing (`Missing API key. Pass it as: Authorization: Bearer `), invalid (`Invalid API key`), or expired (`This API key has expired`). content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '404': description: '`not_found`: no such active list in this workspace.' content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '405': description: Method not allowed — see the `Allow` response header. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '409': description: >- `list_name_taken`: a new list’s name is already used; `idempotency_conflict`: the key was used for a different request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '429': description: >- Rate limit exceeded for this workspace. Retry after the number of seconds in the `Retry-After` header (60). Rate-limited calls are never billed. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '500': description: '`internal_error`: the write failed on our side.' content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error security: - workspaceApiKey: [] components: securitySchemes: workspaceApiKey: type: http scheme: bearer description: >- Workspace API key (`loice_sk_` + 48 hex characters), created under Settings → API Keys. Sent as `Authorization: Bearer loice_sk_…`. Invalid, missing, or expired keys are rejected with 401 before any billable work happens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.