> ## 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.

# Name parsing

> Split a person's full name into the given name and the surname, one name or a list.

`POST /api/v1/name/parse` splits one person's full name into the given name and the surname, in
whatever order it was written: `Smith, John`, `PODSEKIN Igor`, `Ludwig van Beethoven`.
`POST /api/v1/name/parse/batch` does the same for up to 100 names in one call. Both are API-key
only.

## What the answer means

| Field | Meaning |
| - | - |
| `given` | Every given-name word, in order: the given name, middle names and the word of a quoted nickname. |
| `surname` | Every surname word, in full: `Ludwig van Beethoven` → `van Beethoven`. |
| `first` / `last` | The split Loice stores a name under. Always equal to `given` / `surname`. |
| `nickname` | A nickname the input put in quotes (`Alexandra "Sasha" Podsekina` → `Sasha`), else `null`. A bracketed word is an aside and is dropped. |
| `source` | `model` when the name model decided which words are the surname; `rule` when the model was not confident enough (or not available) and the first word was taken as the given name and the rest as the surname. |
| `confidence` | The model's probability for its whole reading whenever it ran, also when the rule answered because the model was below its threshold. `null` only when the model was not available. |
| `bothOrders` | `true` when the order is genuinely ambiguous (`Wang Wei`). The answer is the model's order. |

The name is cleaned first: leading honorifics, credentials, pronouns and bracketed asides are
dropped, so `Dr. Jane Doe, PhD` is given `Jane`, surname `Doe`. With `"spelling": "folded"` the
words come back in lower case without diacritics (`José Núñez` → `jose` / `nunez`); the default,
`as-written`, keeps them as you sent them.

## One name

```bash theme={null}
curl https://app.loice.ai/api/v1/name/parse \
  -H "Authorization: Bearer $LOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-row-17" \
  -d '{ "name": "Ludwig van Beethoven" }'
```

```json theme={null}
{
  "data": {
    "first": "Ludwig",
    "last": "van Beethoven",
    "given": "Ludwig",
    "surname": "van Beethoven",
    "nickname": null,
    "source": "rule",
    "confidence": 0.878,
    "bothOrders": false,
    "charged": true,
    "pointsCharged": "…",
    "balance": { "available": "…", "reserved": "…", "granted": "…" },
    "replay": false
  }
}
```

Here the model was below its confidence threshold, so the rule answered (`source: "rule"`) and
`confidence` still tells you how sure the model was. `charged`, `pointsCharged` and `balance` say
what this call consumed and what is left (elided here: this site states no prices); see
[Billing](#billing) below.

A name that does not split into two parts is refused with `400 invalid_input`: one word
(`Cher`), a surname withheld to an initial (`Jane D.`), only noise (`Dr.`), or words in a script
the parser does not split (`Иванов Иван Иванович`).

## A list of names

```bash theme={null}
curl https://app.loice.ai/api/v1/name/parse/batch \
  -H "Authorization: Bearer $LOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-page-3" \
  -d '{ "names": ["Smith, John", "Cher", "PODSEKIN Igor"] }'
```

Each name gets one result, in the order you sent them. An answered name is `{ "data": … }` (the
single answer without `balance`); a refused one is `{ "error": { "code", "message" } }`:

```json theme={null}
{
  "data": {
    "results": [
      { "data": { "given": "John", "surname": "Smith", "source": "model", "charged": true, "replay": false } },
      { "error": { "code": "invalid_input", "message": "The name cannot be split into a given name and a surname" } },
      { "data": { "given": "Igor", "surname": "PODSEKIN", "source": "model", "charged": true, "replay": false } }
    ],
    "pointsCharged": "…",
    "replay": false,
    "balance": { "available": "…", "reserved": "…", "granted": "…" }
  }
}
```

(Rows abbreviated: every answered row carries all the fields of the single answer, including
its own `pointsCharged`. The request's `pointsCharged` is the sum of its rows.)

A blank name, or one longer than 256 characters, is that row's `validation_error`; the rest of
the batch is still answered. An empty list, more than 100 names, or an element that is not a
string refuses the whole request with `400 validation_error`.

## Billing

* **Every answered name is billed once**, at the `name_parse` price, whether the model or the
  rule decided the order.
* **A refused name is never billed**: `invalid_input`, `validation_error`, a rate-limited call,
  `insufficient_credits`, or a charge that could not be completed (`503 incomplete`).
* **A replay is never billed.**
* In a batch, each answered row is billed on its own; refused rows cost nothing. Before any row
  runs, a batch the workspace cannot pay one answer per row for is refused whole with
  `402 insufficient_credits` and `error.meta = { required, available, shortfall }`.

This site states no prices; see [Billing and points](/billing) for where the current cost is.

## The Idempotency-Key

* **Optional for one name**, **required for a batch**: without it a batch is `400
  validation_error` and nothing is charged.
* Retrying with the same key and the same body returns the same answer with `replay: true` and
  `pointsCharged: 0`. In a batch, every answered row replays for free.
* Reusing a key with a different body (another name, another list, another `spelling`) is
  `409 idempotency_conflict`. For a batch this is decided for the whole request before any row
  runs, so no row of the new list is billed.
* **The key is stored as you send it. Never put a name, an email or other personal data in it.**
  Use a row number, a page number or a random value.

See [Idempotency](/idempotency) for the general rules.

## Limits

* One name: at most 256 characters.
* One batch: 1 to 100 names, and one batch counts as one request against its own
  [rate-limit](/rate-limits) budget.

## Privacy

The names you send and the answers are not stored, not logged and not cached. The billing record
of an answered name holds an opaque key, a one-way fingerprint of the request, its state and its
charge, never the name or the answer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.