Validate name data
POSThttps://api.foxentry.com/name/validate
Foxentry allows you to check the validity and real existence of names and their combinations. At least one parameter is required in the query. You can either write down the name separately or use nameSurname as connected parameter.
Pay attention to the query options. Especially validationDepth, which determines how strict the validation should be based on your use case. For example you'd want minimal validationDepth for web forms since you usually don't want to disturb the user too much with error messages and suggestions.
Foxentry validator is able not only to evaluate the validity of the entered information but it also can fix various typos, errors and missing data. Foxentry can also suggest more suitable alternatives to the data sent in query. Please pay attention to the result, resultCorrected and suggestions in the response.
Always check result.proposal in the response for a proposed solution by Foxentry how you should process the response in your form or application.
Headers
Api-VersionstringAuthorizationstringrequiredBody params
requestobjectrequiredCustom ID assigned by you if you need so.
queryobjectrequiredParameters you want to validate or search for. Use one of the forms: Separate field for name and surname or One field for name and surname.
First name.
Last name / family name.
Name and surname together.
optionsobjectOptions that change how the endpoint behaves.
Data scope of returned data. In full datascope information like gender, vocative and date of the name days is returned.Default
basicAllowed data sources. You can specify the exact data sources that should be used by the validator. This option is not available for the endpoints that do not use any internal databases (e-mails, phone numbers).Default
["CZ", "SK"]Allow to enter a title directly into the name, surname or nameSurname input. For example "Ing. Jan Novák" would be considered as valid/invalid nameSurnameDefault
falseAllow to insert context directly into name, surname or nameSurname. For example "Jan Novák ml." or "Jan Novák mladší" would be considered as valid/invalid nameSurnameDefault
falseThis option determines how automatic corrections are handled. You can choose between full to allow all corrections, format to fix formatting only, suggestion to return corrected data in suggestions, or none for no corrections to be applied.Default
fullLanguage in which various salutations and name-related outputs are returned (e.g. vocative forms such as "pane inženýre").Default
csclientobjectInformation about your user, to make results more relevant.
IP address of your end user (IPv4 or IPv6). Used for geolocation to make results — for example for the search endpoints — more relevant to the user's location. If you have the user's GPS coordinates, prefer sending those via location, as an IP address may be less precise.
Country code in ISO-3166-1 alpha-2 format.
Client's latitude
Client's longitude
Empty fields use the example value shown in grey. Everything you type here is written into the request on the right, and the other way round.
Responses
Response body · application/json
statusintegerStatus of API response.
requestobjectendpointstringcodestringCode of request.
customIdstring | nullCustom ID assigned by you if you need so.
queryobjectSeparate field for name and surname
namestring | nullFirst name.
surnamestring | nullLast name / family name.
nameSurnamestring | nullName and surname together.
optionsobjectQuery options.
dataScopestringData scope of returned data. In full datascope information like gender, vocative and date of the name days is returned.
basicfulldataSourcearray[string]Allowed data sources. You can specify the exact data sources that should be used by the validator. This option is not available for the endpoints that do not use any internal databases (e-mails, phone numbers).
acceptDegreesbooleanAllow to enter a title directly into the name, surname or nameSurname input. For example "Ing. Jan Novák" would be considered as valid/invalid nameSurname
acceptContextbooleanAllow to insert context directly into name, surname or nameSurname. For example "Jan Novák ml." or "Jan Novák mladší" would be considered as valid/invalid nameSurname
correctionModestringThis option determines how automatic corrections are handled. You can choose between full to allow all corrections, format to fix formatting only, suggestion to return corrected data in suggestions, or none for no corrections to be applied.
fullformatsuggestionnonedataLanguagestringLanguage in which various salutations and name-related outputs are returned (e.g. vocative forms such as "pane inženýre").
encsskplclientobjectAdditional information about your user (from whom you've obtained the data sent in query) to increase relevance of the results. If you do not wish to provide this information, you can limit results to relevant countries using the dataSource parameter present in some modules.
ipstringIP address of your end user (IPv4 or IPv6). Used for geolocation to make results — for example for the search endpoints — more relevant to the user's location. If you have the user's GPS coordinates, prefer sending those via location, as an IP address may be less precise.
countrystringCountry code in ISO-3166-1 alpha-2 format.
locationobjectLatitude & longitude of the client's approximate location.
latnumberClient's latitude
lonnumberClient's longitude
responseobjectresultobjectEvaluation of the sent query.
isValidbooleanDetermines the validity of the response. True = valid response / False = invalid response. Can be also null, which indicates a non-specific error.
proposalstringProposed solution by Foxentry how you should process the response in your form or application. The value is composed of three parts: the validity of result, the validity of resultCorrected (appending WithCorrection or WithPartialCorrection), and the presence of suggestions (appending WithSuggestion). It is always a string and is never null. Complete list of possible values: - valid - validWithSuggestion - invalid - invalidWithSuggestion - invalidWithCorrection - invalidWithCorrectionWithSuggestion - invalidWithPartialCorrection - invalidWithPartialCorrectionWithSuggestion
validvalidWithSuggestioninvalidinvalidWithSuggestioninvalidWithCorrectioninvalidWithCorrectionWithSuggestioninvalidWithPartialCorrectioninvalidWithPartialCorrectionWithSuggestiondataTypesobjectList of data types that were evaluated as valid and invalid. Provides information about which query fields were deemed valid and invalid.
validarray[string]invalidarray[string]dataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nullvocativeNamestring | nullVocative form of first name.
vocativeSurnamestring | nullVocative form of surname.
vocativeNameSurnamestring | nullVocative form of name and surname together.
detailsarray[object]typestringType of detail.
namesurnamenameSurnamevaluestringValue of detail.
genderstringGender of name. 0 for unspecified, 1 for men, 2 for women
012vocativestringVocative form of value.
nameDaysarray[object] | nullDate of the name day. Currently works only for czech and slovak names.
errorsarray[object]List of errors related to the query. Provides information about which query fields were deemed invalid and why.
groupstringGroup of error.
SYNTAXtypestringType of error.
CHARACTERSINVALIDUNABLE_TO_PROCESSVALUE_LENGTHVALUE_PART_EXTRAVALUE_PART_MISSINGsubtypestringSubtype of error.
NOT_ALLOWEDWHITESPACESTOO_LONGTOO_SHORTCONTEXTseveritystringSeverity of error. Info = cosmetic changes that don't change the overall meaning. Warning = typos and other errors that could affect the meaning. Critical = critical errors.
infowarningcriticalrelatedToarray[string]List of the affected inputs.
descriptionstring | nullDescription of error.
resultCorrectedobjectName validation result
isValidbooleanDetermines the validity of the response. True = valid response / False = invalid response. Can be also null, which indicates a non-specific error.
proposalstringProposed solution by Foxentry how you should process the response in your form or application.
validvalidWithSuggestioninvalidinvalidWithCorrectioninvalidWithPartialCorrectioninvalidWithSuggestioninvalidWithCorrectionWithSuggestiondataTypesobjectList of data types that were evaluated as valid and invalid. Provides information about which query fields were deemed valid and invalid.
validarray[string]invalidarray[string]dataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nullvocativeNamestring | nullVocative form of first name.
vocativeSurnamestring | nullVocative form of surname.
vocativeNameSurnamestring | nullVocative form of name and surname together.
detailsarray[object]typestringType of detail.
namesurnamenameSurnamevaluestringValue of detail.
genderstringGender of name. 0 for unspecified, 1 for men, 2 for women
012vocativestringVocative form of value.
nameDaysarray[object] | nullDate of the name day. Currently works only for czech and slovak names.
errorsarray[object]List of errors related to the query. Provides information about which query fields were deemed invalid and why.
groupstringGroup of error.
SYNTAXtypestringType of error.
CHARACTERSINVALIDUNABLE_TO_PROCESSVALUE_LENGTHVALUE_PART_EXTRAVALUE_PART_MISSINGsubtypestringSubtype of error.
NOT_ALLOWEDWHITESPACESTOO_LONGTOO_SHORTCONTEXTseveritystringSeverity of error. Info = cosmetic changes that don't change the overall meaning. Warning = typos and other errors that could affect the meaning. Critical = critical errors.
infowarningcriticalrelatedToarray[string]List of the affected inputs.
descriptionstring | nullDescription of error.
fixesarray[object]List of all changes applied to the query data in order to get the suggested result.
groupstringGroup of fix.
FORMATVALUEtypestringType of fix.
CHANGEDsubtypestringSubtype of fix.
CASE_SENSITIVITYDIACRITICSWHITESPACESTYPONonedataobjectData that has been changed
typeFromstringOriginal type of changed value
typestringNew type of value
valueFromstringOriginal value
valuestringChanged value
suggestionsarray[object]isValidbooleanDetermines the validity of the response. True = valid response / False = invalid response. Can be also null, which indicates a non-specific error.
proposalstringProposed solution by Foxentry how you should process the response in your form or application.
validvalidWithSuggestioninvalidinvalidWithCorrectioninvalidWithPartialCorrectioninvalidWithSuggestioninvalidWithCorrectionWithSuggestiondataTypesobjectList of data types that were evaluated as valid and invalid. Provides information about which query fields were deemed valid and invalid.
validarray[string]invalidarray[string]dataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nullvocativeNamestring | nullVocative form of first name.
vocativeSurnamestring | nullVocative form of surname.
vocativeNameSurnamestring | nullVocative form of name and surname together.
detailsarray[object]typestringType of detail.
namesurnamenameSurnamevaluestringValue of detail.
genderstringGender of name. 0 for unspecified, 1 for men, 2 for women
012vocativestringVocative form of value.
nameDaysarray[object] | nullDate of the name day. Currently works only for czech and slovak names.
errorsarray[object]List of errors related to the query. Provides information about which query fields were deemed invalid and why.
groupstringGroup of error.
SYNTAXtypestringType of error.
CHARACTERSINVALIDUNABLE_TO_PROCESSVALUE_LENGTHVALUE_PART_EXTRAVALUE_PART_MISSINGsubtypestringSubtype of error.
NOT_ALLOWEDWHITESPACESTOO_LONGTOO_SHORTCONTEXTseveritystringSeverity of error. Info = cosmetic changes that don't change the overall meaning. Warning = typos and other errors that could affect the meaning. Critical = critical errors.
infowarningcriticalrelatedToarray[string]List of the affected inputs.
descriptionstring | nullDescription of error.
fixesarray[object]List of all changes applied to the query data in order to get the suggested result.
groupstringGroup of fix.
FORMATVALUEtypestringType of fix.
CHANGEDsubtypestringSubtype of fix.
CASE_SENSITIVITYDIACRITICSWHITESPACESTYPONonedataobjectData that has been changed
typeFromstringOriginal type of changed value
typestringNew type of value
valueFromstringOriginal value
valuestringChanged value
errorsarray[string]List of errors related to the request. Should be empty if the request finished successfully.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.