Name API — FIRSTNAMESUGGEST

Support DQE
Support DQE
  • Updated

Use this endpoint to suggest first names based on user input.

Related Name documentation:

GET request

Endpoint

https://{SERVER_ADDRESS}/FIRSTNAMESUGGEST/?Firstname={FIRST_NAME}&Gender={GENDER}&NBResponse={NUM}&Licence={LICENCE_CODE}&Country={COUNTRY_CODE}&Format={FORMAT}&Verifname=Y

Replace the values in braces with your own information:

Parameter Value Description Mandatory/Optional
Licence {LICENCE_CODE} Licence code assigned to your account. Mandatory
Firstname {FIRST_NAME} Part of the first name already entered by the user. Mandatory
Gender {GENDER} M, F, or I. Optional
NBResponse {NUM} Maximum number of suggestions to return. Optional. Default: 10.
Country {COUNTRY_CODE} ISO 3-letter country code used to prioritize suggestions. Optional
Format {FORMAT} Desired output format. Optional. Default: 0.
Verifname Y Checks whether the first name exists without autocomplete. Optional

Format values

Format Description
0 First name in uppercase without accents.
1 First letter uppercase without accents.
2 First name in lowercase without accents.

POST request

Endpoint

https://{SERVER_ADDRESS}/FIRSTNAMESUGGEST/

Add the following parameters in the request body using x-www-form-urlencoded.

Parameter Value Description Mandatory/Optional
Licence {LICENCE_CODE} Licence code assigned to your account. Mandatory
Firstname {FIRST_NAME} Part of the first name already entered by the user. Mandatory
Gender {GENDER} M, F, or I. Optional
NBResponse {NUM} Maximum number of suggestions to return. Optional. Default: 10.
Country {COUNTRY_CODE} ISO 3-letter country code used to prioritize suggestions. Optional
Format {FORMAT} Desired output format. Optional. Default: 0.
Verifname Y Checks whether the first name exists without autocomplete. Optional

Format values

Format Description
0 First name in uppercase without accents.
1 First letter uppercase without accents.
2 First name in lowercase without accents.

Response

Success response

The JSON response is a dictionary containing the suggest key. Its value is an array of suggested items. Each item is an array of two strings: the first value is the gender of the first name (M, F, or I), and the second value is the suggested first name.

Key Description France International
suggest[X][0] F: feminine
M: masculine
I: unknown		 STRING(1) STRING(1)
suggest[X][1] Associated first name. STRING(255) STRING(255)

Example:

{
  "suggest": [
    ["F", "ALICE"],
    ["F", "ALICE-ANNE"],
    ["F", "ALICE-MARIE"]
  ]
}

Error response

Error type Request example Response type
Missing, empty, or incorrect Licence parameter https://{SERVER_ADDRESS}/FIRSTNAMESUGGEST/?Firstname=Laur&Gender=F&NBResponse=10 {}
Missing or empty Firstname parameter https://{SERVER_ADDRESS}/FIRSTNAMESUGGEST/?Gender=F&NBResponse=10&Licence={LICENCE_CODE} {"suggest": []}
Parameter typo https://{SERVER_ADDRESS}/FIRSTNAMESUGGEST/?Firtname=Laur&Gender=F&NBResponse=10&Licence={LICENCE_CODE} {"suggest": []}

Related to

Was this article helpful?

0 out of 0 found this helpful