Names

This service can standardize and validate names, and determine the gender corresponding to a name.

Summary

Names	This service can standardize and validate names, and determine the gender corresponding to a name.
Service methods
namesDetermineGender	Determines the gender of a name.
namesValidateName	Validates a name.
namesStandardizeName	Standardizes a name.
Type definitions
NamesGenderResult
NamesValidationResult	A name validation result.
NamesStandardizationResult	A name split in separate parts.

Service methods

namesDetermineGender

Determines the gender of a name. In case the gender could not be determined, an error is returned.

A name can be supplied either formatted or unformatted. When formatted, the name is split in different parts such as first name and surname. The input fields form_of_address till name_qualifier are used for input of a formatted name. The field surname_first is mandatory when inputting a formatted name. When a name is unformatted, it consists of a single freeform string, where the parts of the name are separated by spaces. The field unformatted_name can be used for such an input.

Parameters

country_code	Two-character ISO country code (NL, FR, GB, DE, BE)
unformatted_name	The name in one string
form_of_address	Form of address, e.g.: Herrn (DE), Monsieur (FR), Mister (GB), De heer (NL)
qualification_preceding	Titles preceding the first name, e.g.: Prof, Dr, Ir
given_names_full	First names
given_names_initials	First name initials
qualification_intermediate_first	Titles preceding the first surname, e.g.: baron
surname_prefix_first	Prefix belonging to the first surname, e.g.: von (DE), de la (FR), van de (NL)
surname_first	First surname. If the surname is not split into parts, the complete surname can be supplied in this field.
indicator	Separator between the first and second surname, usually a hyphen
qualification_intermediate_second	Titles preceding the second surname
surname_prefix_second	Prefix belonging to the second surname
surname_second	Second surname
qualification_succeeding	Titles succeeding the surname, e.g.: MA (DE), ri (FR), BA, OBE (GB), r.i. (NL)
name_qualifier	E.g.: sr, jr

Returns

out	A NamesGenderResult.

namesValidateName

Validates a name. The format of the name is checked and the names and titles are checked against known titles and names. This method returns a status code indicating which part of the name is incorrect, if any.

Parameters

country_code	Two-character ISO country code (NL, FR, GB, DE, BE)
unformatted_name	The name in one string
form_of_address	Form of address, e.g.: Herrn (DE), Monsieur (FR), Mister (GB), De heer (NL)
qualification_preceding	Titles preceding the first name, e.g.: Prof, Dr, Ir
given_names_full	First names
given_names_initials	First name initials
qualification_intermediate_first	Titles preceding the first surname, e.g.: baron
surname_prefix_first	Prefix belonging to the first surname, e.g.: von (DE), de la (FR), van de (NL)
surname_first	First surname. If the surname is not split into parts, the complete surname can be supplied in this field.
indicator	Separator between the first and second surname, usually a hyphen
qualification_intermediate_second	Titles preceding the second surname
surname_prefix_second	Prefix belonging to the second surname
surname_second	Second surname
qualification_succeeding	Titles succeeding the surname, e.g.: MA (DE), ri (FR), BA, OBE (GB), r.i. (NL)
name_qualifier	E.g.: sr, jr

Returns

out	A NamesValidationResult.

namesStandardizeName

Standardizes a name. This function parses the name, returning all parts of the name separately.

A name can be supplied either formatted or unformatted. When formatted, the name is split in different parts such as first name and last name. The input fields form_of_address till name_qualifier can be used to input a formatted name. The field surname_first is mandatory when inputting a formatted name. When a name is unformatted, it consists of a single freeform string, where the parts of the name are separated by spaces. The field unformatted_name can be used to input such a name.

Parameters

country_code	Two-character ISO country code (NL, FR, GB, DE, BE)
unformatted_name	The name in one string
form_of_address	Form of address, e.g.: Herrn (DE), Monsieur (FR), Mister (GB), De heer (NL)
qualification_preceding	Titles preceding the first name, e.g.: Prof, Dr, Ir
given_names_full	First names
given_names_initials	First name initials
qualification_intermediate_first	Titles preceding the first surname, e.g.: baron
surname_prefix_first	Prefix belonging to the first surname, e.g.: von (DE), de la (FR), van de (NL)
surname_first	First surname. If the surname is not split into parts, the complete surname can be supplied in this field.
indicator	Separator between the first and second surname, usually a hyphen
qualification_intermediate_second	Titles preceding the second surname
surname_prefix_second	Prefix belonging to the second surname
surname_second	Second surname
qualification_succeeding	Titles succeeding the surname, e.g.: MA (DE), ri (FR), BA, OBE (GB), r.i. (NL)
name_qualifier	E.g.: sr, jr
function	Profession, e.g.: Arzt (DE), médecin (FR), doctor (GB), huisarts (NL)

Returns

out	A NamesStandardizationResult.

Type definitions

NamesGenderResult

gender	’male’ or ‘female’.
multiple_names	Boolean indicating whether multiple names were detected. If so, the gender applies to the first name that was detected. For example, when a name like “Anne and George Johnson” is supplied, multiple_names is true and the gender is ‘female’.

NamesValidationResult

A name validation result.

code

A number indicating the result of the validation.

300	Success: name is correctly formatted
302	Incorrect order of titles: ‘subject’ (the subject fields contains the titles in question)
304	Surname ‘subject’ does not occur without a prefix
305	Surname ‘subject’ does not occur with given prefix
306	Unknown surname: ‘subject’
307	Unknown first name: ‘subject’
309	Several consecutive titles between first name and the surname (country GB)
312	Title probably needs a full first name
315	Conflicting title items
317	Surname is not noble
318	Form of address does not correspond with titles
330	Multiple successive noble titles in a name, e.g.: F. baron graaf Six
338	Wrong sequence of titles after the name
341	Surname ‘subject’ only found without prefix
342	Surname ‘subject’ does not occur with given prefix

subject

The part of the name which is incorrect, if applicable.

multiple_names

Boolean indicating whether multiple names were detected. If so, results are for the first name that was detected. For example, when a name like “Anne and George Johnson” is supplied, multiple_names is true and the results are for “Anne Johnson”.

NamesStandardizationResult

A name split in separate parts.

form_of_address	Form of address, e.g.: Herrn (DE), Monsieur (FR), Mister (GB), De heer (NL)
qualification_preceding	Titles preceding the first name, e.g.: Prof, Dr, Ir
given_names_full	First names
given_names_initials	First name initials
qualification_intermediate_first	Titles preceding the first surname, e.g.: baron
surname_prefix_first	Prefix belonging to the first surname, e.g.: von (DE), de la (FR), van de (NL)
surname_first	First surname
indicator	Separator between the first and second surname, usually a hyphen
qualification_intermediate_second	Titles preceding the second surname
surname_prefix_second	Prefix belonging to the second surname
surname_second	Second surname
qualification_succeeding	Titles succeeding the surname, e.g.: MA (DE), ri (FR), BA, OBE (GB), r.i. (NL)
name_qualifier	E.g.: sr, jr
function	Profession, e.g.: Arzt (DE), médecin (FR), doctor (GB), huisarts (NL)
multiple_names	Boolean indicating whether multiple names were detected. If so, results are for the first name that was detected. For example, when a name like “Anne and George Johnson” is supplied, multiple_names is true and the results are for “Anne Johnson”.