Search by task, endpoint, field, or error.

← Docs

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 answer valid: false. Junk is a valid question, so it is a 200, never a 404.

Parse

GET
api.parseapi.com/name/{name}
Normalized name, validity, prefix, first, middle, last and suffix
Explore
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, salutation, short and directory formats, and initials. Included on paid plans.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("GRACE HOPPER");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "name": "Grace Hopper",
  "valid": true,
  "prefix": null,
  "first": "Grace",
  "middle": null,
  "last": "Hopper",
  "suffix": null
}

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.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("OSCAR DE LA HOYA");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "name": "Oscar de la Hoya",
  "valid": true,
  "prefix": null,
  "first": "Oscar",
  "middle": null,
  "last": "de la Hoya",
  "suffix": null
}

Display formats

Add ?deep=true on a paid plan for a short name, a directory name, and initials. These sit directly in deep, ready for contact lists and profiles. Invalid names return null for all three.

Run this Deep example with a paid-plan key. Deep is included in the pooled request, with no separate lookup charge.

SDK quickstart
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?

Example response
{
  "name": "Robert James Smith",
  "valid": true,
  "prefix": null,
  "first": "Robert",
  "middle": "James",
  "last": "Smith",
  "suffix": null,
  "deep": {
    "gender": "male",
    "salutation": "Mr",
    "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.

Run this Deep example with a paid-plan key. Deep is included in the pooled request, with no separate lookup charge.

SDK quickstart
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?

Example response
{
  "name": "太郎 山田",
  "valid": true,
  "prefix": null,
  "first": "太郎",
  "middle": null,
  "last": "山田",
  "suffix": null,
  "deep": {
    "gender": "male",
    "salutation": "Mr",
    "short": "山田太郎",
    "directory": "山田太郎",
    "initials": "太"
  }
}

Gender

Request ?deep=true on a paid plan for gender and salutation. Core parsing does not require a dictionary match.

deep.gender answers when the evidence is clear. Ambiguous first names like Taylor and Jordan return null. deep.salutation follows gender: Mr, Ms, or 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

?deep=true Gender evidence, salutation, short and directory formats, and initials. Included on paid plans.

Run this Deep example with a paid-plan key. Deep is included in the pooled request, with no separate lookup charge.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.name("Dr. Jane Smith Jr.", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "name": "Jane Smith",
  "valid": true,
  "prefix": "Dr",
  "first": "Jane",
  "middle": null,
  "last": "Smith",
  "suffix": "Jr",
  "deep": {}
}

Deep fields

deep.genderstring or null
male or female from name evidence, optionally scoped by ?country=. Ambiguous or unsupported evidence stays null
deep.salutationstring or null
Mr or Ms from gender, null when gender is null
deep.shortstring or null
Compact name using name_locale formatting rules, such as R.J. Smith. Null when the name is invalid
deep.directorystring or null
Name formatted for directory listings, such as Smith, Robert James. Null when the name is invalid
deep.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