> ## 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 person's name > Splits one person's full name into the given name and the surname, in any written order: `Smith, John`, `PODSEKIN Igor`, `Ludwig van Beethoven`. The platform cleans the name first (leading honorifics, credentials, pronouns and bracketed asides are dropped), then its name model decides which words are the surname; when the model is not confident or not available, the first word is the given name and the rest the surname (`source: rule`). `given` and `surname` keep every word (middle names, `van`); `nickname` is a nickname the input put in quotes. A name that does not split into two parts (one word, a surname withheld to an initial, only noise, or a script the parser does not split) is refused with 400 `invalid_input` and never billed. Nothing about the name is stored or logged. API key only; rate limited per workspace. For a list, use `POST /api/v1/name/parse/batch`. #### Billing - charged per answered name — whether the name model or the first-word/last-word rule decided the order — never on a refusal, an unsplittable name or a replay. 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 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: post: summary: Parse a person's name description: >- Splits one person's full name into the given name and the surname, in any written order: `Smith, John`, `PODSEKIN Igor`, `Ludwig van Beethoven`. The platform cleans the name first (leading honorifics, credentials, pronouns and bracketed asides are dropped), then its name model decides which words are the surname; when the model is not confident or not available, the first word is the given name and the rest the surname (`source: rule`). `given` and `surname` keep every word (middle names, `van`); `nickname` is a nickname the input put in quotes. A name that does not split into two parts (one word, a surname withheld to an initial, only noise, or a script the parser does not split) is refused with 400 `invalid_input` and never billed. Nothing about the name is stored or logged. API key only; rate limited per workspace. For a list, use `POST /api/v1/name/parse/batch`. #### Billing - charged per answered name — whether the name model or the first-word/last-word rule decided the order — never on a refusal, an unsplittable name or a replay. 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: >- Optional, 1–255 printable ASCII characters, scoped to your workspace. Send the same key when you retry the same request: the original outcome is replayed (`replay: true`, `charged: false`, `pointsCharged: 0`) instead of running and charging again. The same key with a different request is refused with 409 `idempotency_conflict`, as is a key reused after its replay record expired (kept 30 days); a key whose first request is still running answers 409 `idempotency_in_progress`. Without a key, every request is a new lookup, billed at most once on its own. required: false description: >- Optional, 1–255 printable ASCII characters, scoped to your workspace. Send the same key when you retry the same request: the original outcome is replayed (`replay: true`, `charged: false`, `pointsCharged: 0`) instead of running and charging again. The same key with a different request is refused with 409 `idempotency_conflict`, as is a key reused after its replay record expired (kept 30 days); a key whose first request is still running answers 409 `idempotency_in_progress`. Without a key, every request is a new lookup, billed at most once on its own. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 256 description: >- The person's full name as you have it, in any order (`Smith, John`, `PODSEKIN Igor`, `Ludwig van Beethoven`). At least one non-blank character, at most 256 characters. 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: - name example: name: SMITH, John spelling: as-written responses: '200': description: >- The name, split. `first`/`last` always equal `given`/`surname`. `charged`, `pointsCharged` and `replay` say what the call cost; a replay is never charged again. content: application/json: schema: 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. 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: - first - last - given - surname - nickname - source - confidence - bothOrders - charged - pointsCharged - replay - balance required: - data example: data: first: John last: SMITH given: John surname: SMITH nickname: null source: model confidence: 0.998 bothOrders: false charged: true pointsCharged: 1 balance: available: 99 reserved: 0 granted: 100 replay: false '400': description: >- Never billed. `validation_error`: `name` is missing (`name is required`), not a string (`name must be a string`), blank, or longer than 256 characters (`name must be at most 256 characters`); `spelling` is not `as-written` or `folded`; or a malformed header (`Idempotency-Key must be 1 to 255 printable ASCII characters`). `invalid_input` (`The name cannot be split into a given name and a surname`): the name is valid text but does not split — one word (`Cher`), a surname withheld to an initial (`Jane D.`), only noise (`Dr.`), or words in a script the parser does not split (`Иванов Иван Иванович`). 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: invalid_input message: The name cannot be split into a given name and a surname '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`): the workspace cannot pay for the answer. 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 '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 request. `idempotency_conflict`: the key was already used with a different request (another name or spelling), or reused after its replay record expired — send a new key. `idempotency_in_progress`: the first request 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 budget is spent. 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 example: error: code: rate_limited message: Rate limit exceeded retryAfterSeconds: 42 '500': description: >- `internal_error` (`Internal error`): an unexpected failure on our side. 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 '503': description: >- `incomplete` (`The parse could not be completed; nothing was charged`): the charge could not be completed. Never billed — retry with the same `Idempotency-Key`. 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.