Search by task, endpoint, field, or error.
Name API
A person's name, split, cased, and checked.
Pass a name the way a form field gave it to you. GRACE HOPPER, smith, john, and Dr. Jane Smith Jr. all come back split into first, middle, and last with prefix and suffix set aside, proper cased, and in first-name-first order.
Role words, company markers and placeholders return HTTP 200 with valid: false.
Parse
Parameters 4
- namestring · path · required
The name as you have it, URL-encoded
Length: 1 to 120 characters
- countrystring · query · optional
Optional ISO2 country context for the name evidence. Does not infer nationality.
Pattern:
^[a-zA-Z]{2}$- name_localestring · query · optional
Optional BCP 47 name-formatting locale, such as en or ja. Defaults to en. Selects supported CLDR 47 rules, using locale parents where available. Unsupported locales return 400. Changes formatting only, not parsing or gender. Never inferred from country, lang or browser language.
Length: 2 to 64 characters
- deepboolean · query · optional
Gender evidence, short and directory formats, and initials. Included automatically on paid plans in API 2.1.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("GRACE HOPPER", { deep: true });
console.log(result);Run on your server with a secret key. Calling from a browser or app?
{
"name": "Grace Hopper",
"valid": true,
"prefix": null,
"first": "Grace",
"middle": null,
"last": "Hopper",
"suffix": null,
"gender": "female",
"short": "G. Hopper",
"directory": "Hopper, Grace",
"initials": "GH"
}Response fields
- namestring
- Cleaned full name, comma flip resolved and proper cased
- validboolean
- Looks like a person's name. Role words, company markers, and placeholders answer false
- prefixstring or null
- Mr, Mrs, Ms, Dr, Prof, and friends, null when absent
- firststring or null
- First name
- middlestring or null
- Middle name or initial, null when absent
- laststring or null
- Last name, name particles included (de la Hoya), null on a single word
- suffixstring or null
- Jr, III, PhD class, null when absent
Casing
Recasing only runs on all-upper or all-lower input. Mixed case passed through as-is, so McIntyre stays McIntyre. Name particles glue to the last name and stay lowercase mid-name.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("OSCAR DE LA HOYA", { deep: true });
console.log(result);Run on your server with a secret key. Calling from a browser or app?
{
"name": "Oscar de la Hoya",
"valid": true,
"prefix": null,
"first": "Oscar",
"middle": null,
"last": "de la Hoya",
"suffix": null,
"gender": "male",
"short": "O. de la Hoya",
"directory": "de la Hoya, Oscar",
"initials": "OD"
}Display formats
Paid plans automatically include a short name, a directory name, and initials directly on the response, ready for contact lists and profiles. Invalid names return null for all three.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("Robert James Smith", { deep: true });
console.log(result);Run on your server with a secret key. Calling from a browser or app?
{
"name": "Robert James Smith",
"valid": true,
"prefix": null,
"first": "Robert",
"middle": "James",
"last": "Smith",
"suffix": null,
"gender": "male",
"short": "R.J. Smith",
"directory": "Smith, Robert James",
"initials": "RJS"
}Formatting uses English rules by default. Pass name_locale, such as ja or fr, to choose the name's formatting rules. Supported locale parents supply regional fallbacks; an unsupported locale returns 400. The rules come from Unicode CLDR 47.
A formatting locale does not change how the input is split, translate names, or select gender evidence. It is never inferred from country or browser language. For surname-first input, use an explicit comma, as in Smith, Robert James.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("山田, 太郎", { deep: true, name_locale: "ja" });
console.log(result);Run on your server with a secret key. Calling from a browser or app?
{
"name": "太郎 山田",
"valid": true,
"prefix": null,
"first": "太郎",
"middle": null,
"last": "山田",
"suffix": null,
"gender": "male",
"short": "山田太郎",
"directory": "山田太郎",
"initials": "太"
}Gender
Paid plans automatically include available gender evidence. Core parsing does not require a dictionary match.
gender answers when the evidence is clear. Ambiguous first names like Taylor and Jordan return null. Pass ?country=IT to use a country's gender evidence. An exact compound name uses its own evidence before falling back to the parsed first name.
Deep
Gender evidence, short and directory formats, and initials. Included automatically on paid plans in API 2.1.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("Dr. Jane Marie Smith Jr.", { deep: true });
console.log(result);Run on your server with a secret key. Calling from a browser or app?
{
"name": "Jane Marie Smith",
"valid": true,
"prefix": "Dr",
"first": "Jane",
"middle": "Marie",
"last": "Smith",
"suffix": "Jr",
"gender": null,
"short": "J.M. Smith",
"directory": "Smith, Jane Marie",
"initials": "JMS"
}Deep fields
- genderstring or null
- male or female from name evidence, optionally scoped by ?country=. Ambiguous or unsupported evidence stays null
- shortstring or null
- Compact name using name_locale formatting rules, such as R.J. Smith. Null when the name is invalid
- directorystring or null
- Name formatted for directory listings, such as Smith, Robert James. Null when the name is invalid
- initialsstring or null
- Name initials using name_locale formatting rules, such as RJS. Null when the name is invalid
Build with Name
All tutorials →Questions? Email