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

countrystring · query · optional

Optional ISO2 country context for the name evidence. Does not infer nationality.

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.

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
}

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("Dr. Jane Smith Jr.");
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"
}

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("Smith, John");
console.log(result);

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

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

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("test test");
console.log(result);

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

Example response
{
  "name": "test test",
  "valid": false,
  "prefix": null,
  "first": null,
  "middle": null,
  "last": null,
  "suffix": null
}

Response fields

name
Cleaned full name, comma flip resolved and proper cased
valid
Looks like a person's name. Role words, company markers, and placeholders answer false
prefix
Mr, Mrs, Ms, Dr, Prof, and friends, null when absent
first
First name
middle
Middle name or initial, null when absent
last
Last name, name particles included (de la Hoya), null on a single word
suffix
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.

Deep examples run with your own key. Check this API’s included units and pricing before running.

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.

Deep examples run with your own key. Check this API’s included units and pricing before running.

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.

Deep examples run with your own key. Check this API’s included units and pricing before running.

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

Build with Name

All tutorials →

Questions? Email