Skip to main content
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

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

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

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" } }:
(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 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 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 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.