Validate name

This endpoint checks if a given name exists and is not made up or misspelled. It also detects if a name is possibly fake by comparing it with names in a database that contains existing famous, fictional and humorous names.

The name validation endpoint is very valuable for contact and registration forms. It does not only parse any given name but it makes sure that people who sign up for your services use a real name. We've compiled a list with use cases on a separate page.

In additional to the 'parse' endpoint we check if the complete name is possibly fake by comparing it with 13.738 famous, fictional and humorous names. We leave the option to you how strict you want to be by returning two boolean parameters called 'pass_loose' and 'pass_strict' for loose and strict validation rules. This way people can never sign up like Clark Kent, Sylvester Stallone or Abraham Lincoln.

Request parameters

Name Required Description Example
api_key required Your API key is required for every API call. Register for a free API key. 93d471ea85d1937e713e8aafffb32090
name required The complete name that you want to validate. Depending on your subscription you can validate multiple names in a single request by making an array out of it.
Example: name[]=John Doe&name[]=Sarah Jones
John Smith
country_code optional If you know the country code associated with the name then you can provide it. By providing the country code the accuracy of the gender will be higher. The country code should be 2 characters according to the ISO 3166-2 country code specification. If the name parameter contains multiple names then the country_code should also be an array. DE
ip optional If you don't know the country code you can always provide an IP address. We convert the IP address to a country_code internally. If the name parameter contains multiple names then the ip should also be an array. 66.249.64.85
response_type optional The API returns JSON objects written in key/value pairs by default. If needed you can also get the response as a JSON array instead. object, array
gender_type optional Different type of kind can be used as a value for gender_formatted. By default the gender field returns "male" or "female". You can change the formatting from sex (default) to gender, marital, birth and slang. sex, gender, marital, birth, slang

Request URL

This is the easiest way to parse and validate a name. Each response is JSON encoded so easy to use. You can copy past the request URL in the address bar of your browser to see the response.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=validate&name=Bob%20Marley

If you know the country code of the name then you can add the country code parameter. By specifying the country code the accuracy of the gender will increase. All endpoints use the ISO 3166-2 for country codes. Check our list of countries to see all supported country codes.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=validate&name=Bob%20Marley&country_code=US

It is possible to query multiple names in a single request. You can send a maximum array of 25 names in the same request. For the rate limit this counts as a single request making it ideal of you want to process high volumes of names. If you also use the country_code then you have to make an array of that as well.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=validate&name[]=Bob%20Marley&name[]=Sarah%20Jones

Response object

{
    results: 1,
    error: null,
    data: [
        {
            salutation: {
                salutation: "Mr.",
                initials: "B.",
                lastname: "Marley"
            },
            title: null,
            name: {
                nickname: null,
                firstname: {
                    name": "Bob",
                    name_ascii: "Bob",
                    validated: true,
                    gender: "m",
                    gender_formatted: "male",
                    unisex: false,
                    gender_deviation: 0,
                    country_code: "US",
                    country_certainty: 60,
                    country_rank: 3,
                    alternative_countries: {
                        GB: 13,
                        CA: 3
                    }
                },
                middlenames: null,
                lastname: {
                    name: "Marley",
                    name_ascii: "Marley",
                    validated: true,
                    country_code: "US",
                    country_certainty: 62,
                    country_rank: 1,
                    alternative_countries: {
                        GB: 24,
                        CA: 3,
                        AU: 3
                    }
                }
            },
            country: {
                country_code: "US",
                country_certainty: 63,
                country_code_alpha: "USA",
                name: "United States",
                continent: "North America",
                demonym: "American",
                primairy_language_code: "en",
                primairy_language: "English",
                currency: "USD",
                alternative_countries: {
                    GB: 19,
                    CA: 3,
                    AU: 3
                }
            }
        },
        validation :{
            pass_loose: false,
            pass_strict: false,
            listed_in: [
                "imdb",
                "pantheon"
            ],
            listed_as: [
                "actor",
                "producer",
                "writer",
                "musician"
            ]
        }
    ]
}

Response parameters

Most response parameters are self-explanatory. However, there are a few fields that need an additional explanation. These fields are listed in the table below. If you're looking for is a response parameter that is not in this list, please contact us and we'll add it to this list.

Name Type Description
validated boolean The validated key is a boolean indicating if a first name, middle name or last name exists in an official database. Most countries and their governments have great open data initiatives and provide official first names, gender and frequencies. For the first name and middle names the validated key is a boolean indicating if the name is also in the official database for the resulting country. If the validated key is 'false' then the name is derived from another country. It's still an existing name but we don't have the official database for that country. For the last name it means it has at least to occur two times in the resulting country.
gender enum The gender is always an "m" (male) or "f" (female). Our database holds 1.597.154 official first names and their gender received from governments. By providing the country_code in the request parameter the accuracy of the gender will be higher.
unisex boolean A unisex name is a given name that can be used by a person regardless of their gender.
gender_deviation integer The gender deviation is a percentage indication the change that the gender is the opposite as provided.
alternative_countries array Each name (first name, middle name or last name) has a country code. The country code is the most likely country where the name originates from. The alternative countries is an array that hold the 'second best' estimations. The values are the country certainty percentages (higher is more likely). After analyzing all names and countries the services makes a selects the most likely country where the complete name originates from.
pass_loose boolean For loose validation a complete name (first name and last name) must be entered. The first name must exist in our database but the last name does not have to exist. The complete name may be 'listed_in' IMDB but not in the 'Pantheon' like Sylvester Stallone or as 'Fictional' like Clark Kent.
pass_strict boolean For strict validation a complete name (first name and last name) must be entered. The first name and last name must both exist in our database. The complete name may be 'listed_in' IMDB but not in the 'Pantheon' like Sylvester Stallone or as 'Fictional' like Clark Kent.
listed_in array For validation we check the complete name our Pantheon (famous people), IMDB (actors, directors and composers) and Fictional (superheroes, villains and fake names). If the name exists in one of these databases then the name of the database will be returned. A name like Sylvester Stallone can be listed in different databases.
listed_as array If a name is listed in the Pantheon, IMDB or Fictional database then this array will contain the occupation. Sylvester Stallone is listed as a actor, director, writer and a superhero.