> ## 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. # Parse a list of names > Parses 1 to 100 names in one request, exactly as `POST /api/v1/name/parse` parses one, and answers one result per name in input order: `{ data }` for an answered name, `{ error: { code, message } }` for a refused one (`invalid_input` for a name that does not split, `validation_error` for a blank or over-long one). Each answered name is billed on its own; refused names cost nothing. The `Idempotency-Key` header is REQUIRED: each answered row is recorded under the key and its position, so retrying the same batch with the same key replays every answered row for free. Before any row runs, the request is refused whole when the key was used for a different batch (409) or when the workspace cannot pay one answer for every row that is not a replay (402). Nothing about the names is stored or logged. API key only; one batch counts once against its own per-workspace budget. #### Billing - charged per answered row, each its own operation — never for a refused row, a refused request or a replayed row. The current cost is shown in the app under Settings → Billing and in the live `GET /api/v1/openapi.json`. Calls that end in a system or provider error (HTTP 500) or are rate limited (HTTP 429) are not billed. The `charged` and `pointsCharged` fields of the response state what this call actually consumed. ## OpenAPI ````yaml /openapi.json post /api/v1/name/parse/batch 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/name/parse/batch: post: summary: Parse a list of names description: >- Parses 1 to 100 names in one request, exactly as `POST /api/v1/name/parse` parses one, and answers one result per name in input order: `{ data }` for an answered name, `{ error: { code, message } }` for a refused one (`invalid_input` for a name that does not split, `validation_error` for a blank or over-long one). Each answered name is billed on its own; refused names cost nothing. The `Idempotency-Key` header is REQUIRED: each answered row is recorded under the key and its position, so retrying the same batch with the same key replays every answered row for free. Before any row runs, the request is refused whole when the key was used for a different batch (409) or when the workspace cannot pay one answer for every row that is not a replay (402). Nothing about the names is stored or logged. API key only; one batch counts once against its own per-workspace budget. #### Billing - charged per answered row, each its own operation — never for a refused row, a refused request or a replayed row. The current cost is shown in the app under Settings → Billing and in the live `GET /api/v1/openapi.json`. Calls that end in a system or provider error (HTTP 500) or are rate limited (HTTP 429) are not billed. The `charged` and `pointsCharged` fields of the response state what this call actually consumed. parameters: - schema: type: string minLength: 1 maxLength: 255 description: >- REQUIRED, 1–255 printable ASCII characters, scoped to your workspace. Each answered row is its own billed operation under this key and the row’s position, so retrying the same batch with the same key replays every answered row for free. The same key with a different batch (any change to `names` or `spelling`) is refused whole with 409 `idempotency_conflict` before any row runs. The key is stored as sent: never put a name or other personal data in it. required: true description: >- REQUIRED, 1–255 printable ASCII characters, scoped to your workspace. Each answered row is its own billed operation under this key and the row’s position, so retrying the same batch with the same key replays every answered row for free. The same key with a different batch (any change to `names` or `spelling`) is refused whole with 409 `idempotency_conflict` before any row runs. The key is stored as sent: never put a name or other personal data in it. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: type: object properties: names: type: array items: type: string minItems: 1 maxItems: 100 description: >- 1 to 100 names, each answered in order. A non-string element refuses the whole request; a blank name or one longer than 256 characters is that row’s `validation_error`. spelling: type: string enum: - as-written - folded description: >- `as-written` (default) returns the words as you sent them, cleaned of honorifics, credentials and asides. `folded` returns the key spelling: lower case, diacritics removed (`José Núñez` → `jose` / `nunez`). required: - names example: names: - Smith, John - Cher - PODSEKIN Igor spelling: as-written responses: '200': description: >- One result per submitted name, in input order. `pointsCharged` is the sum of the rows; `replay` is true when every answered row replayed an earlier call with this key. content: application/json: schema: type: object properties: data: type: object properties: results: type: array items: anyOf: - type: object properties: data: type: object properties: first: type: string description: >- The given name Loice stores the person under; always equal to `given`. last: type: string description: >- The surname Loice stores the person under; always equal to `surname`. given: type: string description: >- Every given-name word, in order: given name, middle names and the word of a quoted nickname. surname: type: string description: >- Every surname word, in full (`Ludwig van Beethoven` → `van Beethoven`). nickname: type: - string - 'null' description: >- A nickname the input put in quotes (`Alexandra "Sasha" Podsekina` → `Sasha`), else null. A bracketed word is an aside and is dropped. source: type: string enum: - model - rule description: >- `model` when the name model decided the order; `rule` (first word given, the rest surname) when the model was not confident or not available. Billed the same. confidence: type: - number - 'null' description: >- The model's probability for its whole reading whenever it ran (also when the rule answered because the model was below its threshold); null when the model was not available. bothOrders: type: boolean description: >- True when the order is genuinely ambiguous (`Wang Wei`); the answer is the model’s order. charged: type: boolean description: Whether this answer consumed points. pointsCharged: type: integer description: >- Points this answer consumed (0 on a replay). replay: type: boolean description: >- True when this answers an earlier call with the same `Idempotency-Key` (never charged again). The answer is recomputed from the request: nothing about the name is stored. required: - first - last - given - surname - nickname - source - confidence - bothOrders - charged - pointsCharged - replay required: - data - type: object properties: error: type: object properties: code: type: string enum: - invalid_input - validation_error - insufficient_credits - incomplete - idempotency_in_progress - idempotency_conflict description: >- Why this row was not answered. A refused row is never charged. message: type: string description: Human-readable explanation. required: - code - message required: - error description: >- Exactly one result per submitted name, in input order: `{ data }` for an answered row (the single answer without `balance`), `{ error: { code, message } }` for a refused one. pointsCharged: type: integer description: 'Points this request consumed: the sum of its rows.' replay: type: boolean description: >- True when every answered row was a replay of an earlier call with this key. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. required: - results - pointsCharged - replay - balance required: - data example: data: results: - data: first: John last: Smith given: John surname: Smith nickname: null source: model confidence: 0.997 bothOrders: false charged: true pointsCharged: 1 replay: false - error: code: invalid_input message: >- The name cannot be split into a given name and a surname - data: first: Igor last: PODSEKIN given: Igor surname: PODSEKIN nickname: null source: model confidence: 0.99 bothOrders: false charged: true pointsCharged: 1 replay: false pointsCharged: 2 replay: false balance: available: 98 reserved: 0 granted: 100 '400': description: >- Never billed. `validation_error`: `names` is missing (`names is required`), empty (`names must contain at least one name`), longer than 100 (`names must contain at most 100 names`) or not all strings (`names must be strings`); `spelling` is not `as-written` or `folded`; the `Idempotency-Key` header is missing (`Idempotency-Key is required for a batch`) or malformed. A blank or over-long name is not a 400: it is that row’s `validation_error`. 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 example: error: code: validation_error message: Idempotency-Key is required for a batch '401': description: >- `unauthenticated`. API key missing (`Missing API key. Pass it as: Authorization: Bearer `), invalid (`Invalid API key`), or expired (`This API key has expired`). A browser session is not a key. Never billed. 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 '402': description: >- `insufficient_credits` (`Insufficient credits`): before any row ran, the workspace could not pay one answer for every row that is not a replay (rows that may turn out unsplittable are counted). `error.meta` = `{ required, available, shortfall }`. Never billed. 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 example: error: code: insufficient_credits message: Insufficient credits meta: required: 3 available: 2 shortfall: 1 '405': description: >- `method_not_allowed` (`Method not allowed`) — see the `Allow` response header. 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 '409': description: >- The `Idempotency-Key` cannot be used for this batch. `idempotency_conflict`: the key was already used for a different batch (any change to `names` or `spelling`), detected for the whole request before any row runs — send a new key. `idempotency_in_progress`: the first batch with this key is still running. Never billed. 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_limited` (`Rate limit exceeded`): this workspace’s name-parse batch budget is spent (one batch counts once). Retry after the `Retry-After` header (also `error.retryAfterSeconds`). Never billed. headers: Retry-After: schema: type: string description: Seconds to wait before calling again. required: true description: Seconds to wait before calling again. 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 '500': description: >- `internal_error` (`Internal error`): an unexpected failure on our side. Rows already answered keep their charge (retry with the same key: they replay for free). 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.