API documentation

Namsor has developed a name checking technology, able to create comprehensive analysis through multiple processing. Our API can classify names by origin, by ethnicity, by residence country, by gender, and supports many alphabets*.

API version: 2.0.21

API key:

API documentation

Introduction

Gender from names

Genderize Name
Gender from first name , last name (optional).
Genderize Name Geo
Gender from first name , last name (optional), country code .
Genderize Full Name
Gender from full name .
Genderize Full Name Geo
Gender from full name , country code .

Origin from names

Name Origin
Origin from first name (optional), last name (optional).
Full Name Origin
Origin from full name .

Diaspora from names

Name Diaspora
Diaspora from first name (optional), last name , country code (optional).
Full Name Diaspora
Diaspora from full name , country code .

Country of residence from names

Name Country
Country of residence from first name (optional), last name (optional).
Full Name Country
Country of residence from full name .
Names Corridor
Interaction from first name , last name , country code , first name , last name , country code .

US race ethnicity from names

Name US Race
US race from first name (optional), last name (optional), country code (optional).
Full Name US Race
US race from full name , country code (optional).
Name US Race ZIP
US race from first name (optional), last name (optional), country code (optional), 5 digit zip code .

Indian names

Caste Indian Name
Caste group from first name (optional), last name (optional), state .
Caste Indian Full Name
Caste group from full name , state .
Religion Indian Name
Religion from first name (optional), last name (optional), state .
Religion Indian Full Name
Religion from full name , state .
Subclassification Indian Name
Indian State or Union territory from first name (optional), last name (optional).
Subclassification Indian Full Name
Indian State or Union territory from full name .

Split full names

Split Name
Split name from full name .
Split Name Geo
Split name from full name , country code .

Name type recognition

Name Type
Name type from proper noun .
Name Type Geo
Name type from proper noun , country code .

Phone number format

Format Phone Number
Phone prefix from first name (optional), last name (optional), phone number .
Format Phone Number Geo
Phone prefix from first name (optional), last name (optional), phone number , country code .

Admin

Introduction

About

The base endpoint URL is: https://v2.namsor.com/NamSorAPIv2
All endpoints require an API Key.
Never share your API key to ANYONE.

API Requests and Responses

All endpoints return JSON containing either an object or a nested array of objects.
Currently certain NamSor API endpoints use nested object structures in their query body and / or responses, please refer yourself to the corresponding code example.
Be aware that data in the code examples have been URL encoded into the corresponding ASCII code characters when necessary, for example 谢晓亮 is replaced by %E8%B0%A2%E6%99%93%E4%BA%AE. URLs cannot contain spaces or non-ASCII characters. When making GET requests to the API use URL encoding to convert non-ASCII characters into a format that can be transmitted over the internet.

Data Privacy

By default Namsor's machine learning algorithm may improve data evaluation based on the data inputs and does store logs of submitted request. You may change these setting either in your user account or by calling the dedicated API endpoints. All data logs are secured using AES encryption before being stored.

If you wish to disable machine learning based on your submissions, please set learnable to false in the "Enhance privacy" section on the my account page. When set to false for an API key, the data processed using that key will not feed the machine learning algorithm.

If you wish to disable service usage history, please set anonymized to true in the "Enhance privacy" section on the my account page. When set to true for an API key, the data processed using that key will be irreversibly anonymised using SHA encryption. Note that the smart processing for redundant queries will still work even if your data is anonymised.

Authentication

API Key Creation

Customer accounts are common to all Namsor group websites. To create an API key visit Namsor or another site of the Namsor group and create an account. Navigate to the account information page to retrieve your API key. Your newly created account comes with 1000 free credits that you may use immediately with any of Namsor's tools: API, CSV and Excel file processor or Developer tools.

API Key Installation

Your API key must be set in the header of your request using the X-API-KEY property. Please refer yourself to the provided code samples for correct key installation.

You must replace your-api-key with your Namsor API key.

Credits

What are Credits

We use a credit system to track usage. Each plan comes with a monthly quantity of credits and a price for request that exceed your monthly allowance. The free Basic subscription plan grants you 1000 credits but other plans are available in case you have higher requirements. As an example, with 1000 credits you can either:

Process 100 names to determine their origins.
Process 50 names to determine their ethnicities.
Process 100 names to determine their US race ethncities.
Process 100 names to determine their countries of residence.
Process 1000 names to determine their genders.

Admin routes are free.

Repeated Operations Tolerance

Our API features smart processing and it will not charge for analyzing identical data for up to 20 times. For example if you submit the same full name 5 times in order to infer it's origin then you will only be charged 1 credit.

Soft Limit vs Hard Limit

In your user account you may set two types of credit usage limits:

A soft limit that will trigger an email notification when reached.
A hard limit that will trigger an email notification and block the API key when reached.

Track Usage

There are two ways to track your credit usage: check the provided graphics in your user account or query the appropriate Admin routes (API Usage, API Usage History and API Usage History Aggregate).

Errors

The NamSor API uses the following error codes:

401UnauthorizedMissing or incorrect API Key.
403ForbiddenAPI Limit Reached or API Key Disabled.
404Not FoundThe specified route could not be found.
500Internal Server ErrorServer error. Try again later.

Result Explainability

The Namsor API offers the ability to obtain a detailed explanation of how the artificial intelligence arrived at its results for a given request. By enabling this option, an additional field is included in the API response, providing a Python code explanation of the process followed by the AI.

Important

Additional Cost: Activating explainability incurs an extra cost of 50 credits per name processed.
Explanation Format: The returned explanation is in Python code. For optimal use, it is recommended to remove tabs and carriage returns so that the code is usable.

How to Activate Explainability:

Contact the Namsor Team: Before using this feature, please contact our team to activate the explainability option on your client account.
Configure the Request: Add the following header to your API request: X-OPTION-EXPLANABILITY: true

X-OPTION-EXPLANABILITY: true

By following these steps, each request will now include a detailed explanation of the result, allowing you to gain deep insights into the workings of our artificial intelligence specialized in onomastics.

AI Act Use Case

The Namsor API can be instrumental in complying with national or supra-national regulations aimed at preventing biased results and discriminatory effects in Artificial Intelligence. Namsor is capable of inferring special categories of personal data from names to estimate the risk of algorithmic biases related to gender, race, cultural/linguistic background, ethnicity, or country of origin.

The European AI Act introduces a new exception regarding “sensitive data” to protect citizens' rights from discrimination that might arise due to bias in AI systems. For the purpose of ensuring bias detection and correction in high-risk AI systems, it permits the processing of special categories of personal data, as a matter of substantial public interest.

Namsor's Explainability Option is designed to provide a closed mathematical formula that includes the entire explanation of name classification (with both training data features and complete model formulas). This can be stored for audit purposes in decision-making AI algorithms.

To protect Namsor's intellectual property, we require specific documentation and a signed NDA before activating this option.