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 inputed 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
falseSpecifies the depth of name validation. In other words how strict the validator should behave. Minimal = all the names are considered valid as long as there are no forbidden characters used or we are 100% sure the name is invalid. Usually the only thing corrected is format. Moderate = something in between the minimal and strict validation. There are more instances of corrections like typos etc. Strict = the most strict validation depth. Missing names in our database are marked as invalid, the scoring for corrections and suggestions is tweaked.Default
strictAllows to correct the name (resultCorrected). If this is disabled, the corrections are given as a suggestion.Default
trueclientobjectInformation about your user, to make results more relevant.
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
validationDepthstringSpecifies the depth of name validation. In other words how strict the validator should behave. Minimal = all the names are considered valid as long as there are no forbidden characters used or we are 100% sure the name is invalid. Usually the only thing corrected is format. Moderate = something in between the minimal and strict validation. There are more instances of corrections like typos etc. Strict = the most strict validation depth. Missing names in our database are marked as invalid, the scoring for corrections and suggestions is tweaked.
minimalmoderatestrictsmartModebooleanAllows to correct the name (resultCorrected). If this is disabled, the corrections are given as a suggestion.
clientobjectAdditional 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.
ipstringcountrystringCountry 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.
validvalidWithSuggestioninvalidinvalidWithCorrectioninvalidWithPartialCorrectioninvalidWithSuggestioninvalidWithCorrectionWithSuggestiondataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nulldetailsarray[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.
countrystringCountry code in format ISO-3166-1 alpha-2.
monthnumberMonth number for name day.
daynumberDay number for name day.
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.
descriptionstringDescription of error.
Disallowed characters were used in the value.Value contains invalid use of spaces.Value has invalid syntax.Cannot be processed due to the invalid syntax.Value is too long.Value is too short.Value contains unneccessary context.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.
dataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nulldetailsarray[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.
countrystringCountry code in format ISO-3166-1 alpha-2.
monthnumberMonth number for name day.
daynumberDay number for name day.
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.
descriptionstringDescription of error.
Disallowed characters were used in the value.Value contains invalid use of spaces.Value has invalid syntax.Cannot be processed due to the invalid syntax.Value is too long.Value is too short.Value contains unneccessary context.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.
dataobjectnameSurnamestring | nullName and surname together.
namestring | nullFirst name.
surnamestring | nullLast name / family name.
contextarray[string]degreesBeforearray[string] | nulldegreesAfterarray[string] | nulldetailsarray[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.
countrystringCountry code in format ISO-3166-1 alpha-2.
monthnumberMonth number for name day.
daynumberDay number for name day.
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.
descriptionstringDescription of error.
Disallowed characters were used in the value.Value contains invalid use of spaces.Value has invalid syntax.Cannot be processed due to the invalid syntax.Value is too long.Value is too short.Value contains unneccessary context.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.