NameAPI is a web API
to handle people's names
in your software.

News

28.04.2016

Version 5 release candidate is online

This is the time to test your installations.


14.03.2016

Faster server failure detection

When one server is on strike, it is removed from the pool instantly.


17.02.2016

Faster trash email domain detection

New domains are caught as soon as they appear.


09.02.2016

Version 5 preview is online

Test the new REST API, give early feedback.


10.11.2015

Announcing Version 5

The next major version will bring a brand new REST API.


   

Person

       
A (natural or legal) person as used in crm databases, online user databases etc.
            
This is the snapshot of a person's personal data. Some attributes like name and marital status can change in time.    
       
<person><addresses><address><country>CA</country> <placeName>Arnprior, Ontario</placeName><postalCode>K2S 0Z7</postalCode><streetInfo> <streetName>Knightbridge Road</streetName><streetNumber>77</streetNumber></streetInfo> </address><usageForAll>true</usageForAll></addresses><ageInfo> <birthDay>16</birthDay><birthMonth>7</birthMonth><birthYear>1984</birthYear> </ageInfo><correspondenceLanguage>en</correspondenceLanguage><emailAddresses> <emailAddress>john.doe@gmail.com</emailAddress></emailAddresses> <gender>MALE</gender><personName><givenNames>John</givenNames> <surnames>Doe</surnames></personName><telNumbers> <fullNumber>(999) 999-9999</fullNumber></telNumbers></person>

personName

Defines a person's names such as given name(s) and surname(s).
Multiple given names may appear in one field. Or they can be added as multiple name items if they are available separately already. The same applies for other name types such as surnames.
false
<personName><givenNames>John</givenNames> <surnames>Doe</surnames></personName>

gender

The gender of the person.
MALE, FEMALE, UNKNOWN
false (defaults to UNKNOWN)
<gender>MALE</gender>

ageInfo

Information about a person's age.
For a NaturalPerson this is the birth-date/age info. For a LegalPerson this is the founding date (activation date).
            
The information may be a complete date such as 1980-12-31, or a year with month such as 1980-12, or just a year such as 1980, or a year range such as 1980-1989.
The month range is 1-12, not 0-11.    
Depends on the service. A validator service may check for valid dates, and report problems (such as 1986-02-31). A genderizer service may use it to filter irrelevant birth statistics.
The behavior on illegal input depends on the web service that is called. Invalid (xml) input such as a non-numeric string should always result in an illegal input exception. An invalid date such as 1986-02-31 may trigger an illegal input exception, or it may just be ignored.
false

<ageInfo><birthDay>16</birthDay><birthMonth>7</birthMonth><birthYear>1984</birthYear></ageInfo>

<ageInfo><birthYear>1984</birthYear></ageInfo>

(todo: add example)


   

addresses

       
Addresses that are used by this person.
            
Multiple addresses may be passed (domicile, mailing/delivery address, ...) or a single address may be responsible for all purposes.
    
Depends on the service. A validator service may check for valid addresses, and report problems (such as invalid zip codes). A genderizer service may use it to better classify the names.
The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid address data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.
       
false. Also, all the address fields are optional too.
       

<addresses><address><country>CA</country> <placeName>Arnprior, Ontario</placeName><postalCode>K2S 0Z7</postalCode><streetInfo> <streetName>Knightbridge Road</streetName><streetNumber>77</streetNumber></streetInfo> </address><usageForAll>true</usageForAll></addresses>

<addresses><address><country>CA</country> <placeName>Arnprior, Ontario</placeName></address><usageForAll>true</usageForAll></addresses>

(todo: add example)


   

telNumbers

       
Phone, fax etc numbers that are used by this person.
            
        Multiple numbers may be added    
            
        Depends on the service.         A data validator service may check for problems. A fake checker may look for suspicious input.    
       
        The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid phone data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.    
       
false
       
               

<telNumbers> <fullNumber>01234/56789</fullNumber></telNumbers>        

   

   

emailAddresses

       
Email addresses that are used by this person.
            
        Multiple addresses may be added.    
            
        Depends on the service. A data validator service may check for problems such as illegal syntax or inexistent domain. A service may check for disposable email addresses. It may be used to extract name information. A validator service may compare the name in the email address with the person's name.    
       
        The behavior on illegal input depends on the web service that is called. A validator service may report problems with invalid email address syntax, or inexistent domain names, etc. Services may throw an invalid input exception.    
       
false
       
               

<emailAddress>john.doe@example.com</emailAddress></emailAddresses>

   

   

correspondenceLanguage

       
The language code for the correspondence language of the person (with you, the company).
            
        ISO-639 code of the language. Either 639-1 or 639-3, for example "it" or "ita" for Italian.    
            
        In combination with the Context.geo it helps the services to better classify the culture of the person.    
       
        The behavior on illegal input depends on the web service that is called. It may ignore it, or throw an invalid input exception.    
       
false
       
               

<correspondenceLanguage>it</correspondenceLanguage>