The Nymeria API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.
You can use the Nymeria API with an API key generated via your account's API page. Any member of the team can leverage the API. All team members share the same pool of account credits.
These docs are a reference for the latest version of the API.
The Nymeria API uses API keys to authenticate requests. You can view and manage your API keys in your Nymeria API page.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub or client side code.
You can leverage the authentication endpoint to test any API key. Once you have a key to test you can run the following request to determine your authentication setup.
curl -X POST https://www.nymeria.io/api/v4/check-authentication -d api_key=<insert-api-key>{
"status": "success",
"data": {
"message": "Great! You have successfully authenticated with the API."
}
}All API responses that consume credits will return credit information in the response headers.
The "call credits spent" header is used to determine how many credits the API request consumed. The "total limit remaining" header will tell you how many credits your account has remaining.
x-call-credits-spent 1
x-total-limit-remaining 9895
Given one or more inputs, Nymeria can locate a person and return a complete profile including the person's contact information. This endpoint is useful if you incomplete profile information and you can to enrich your data with new or updated data.
The following query parameters are valid:
Optionally, you can provide a filter parameter or a require parameter to filter out certain kinds of data and require other kinds of data. For example, you can filter out professional email addresses and require an email address, phone number or personal email address.
At this time, the only valid filter parameters are professional-emails, personal-emails and educational-emails which can be used to filter out the respective email types. You can provide multiple filters using a command. For example, you can filter professional and educational emails with professional-emails,educational-emails
The require parameter has a number of valid values. You can require any of the following data points:
Note, you can use multiple requirements by separating them via a comma. For example, you can require an email and a phone number with require=email,phone.
A single credit is taken for each successful enrichment. If no additional information is returned in a request then no credit will be deducted. Furthermore, if the same data is returned within a 30 day window only a single credit is deducted.
curl https://www.nymeria.io/api/v4/person/enrich?profile=linkedin.com/in/aaron-smith-0a072a22 -H "X-Api-Key: INSERT_API_KEY"{
"data": {
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"first_name": "Aaron",
"last_name": "Smith",
"full_name": "Aaron Smith",
"gender": null,
"age": null,
"birth_year": null,
"birth_date": null,
"work_email": "aaron_smith@mastercard.com",
"personal_emails": [
"aaronsmith@gmail.com"
],
"emails": [
{
"type": "professional",
"name": "aaron_smith",
"domain": "mastercard.com",
"address": "aaron_smith@mastercard.com"
},
{
"type": "personal",
"name": "aaronksmith",
"domain": "gmail.com",
"address": "aaronsmith@gmail.com"
},
{
"type": "personal",
"name": "punksrus",
"domain": "yahoo.com",
"address": "punksrus@yahoo.com"
}
],
"mobile_phone": "+13362112012",
"phone_numbers": [
"+13362112012"
],
"industry": "Information Technology And Services",
"location_name": "Leander, Texas, United States",
"location_last_updated": "2020-10-01",
"location_country": "United States",
"inferred_years_of_experience": null,
"inferred_salary": null,
"job_title": "Senior Software Engineer",
"job_title_role": "Engineering",
"job_title_levels": [
"senior"
],
"job_start_date": "2019-11",
"job_company_name": "Clear Channel",
"job_company_website": null,
"job_company_founded": null,
"job_company_size": null,
"job_company_linkedin_url": null,
"job_last_updated": "2020-09-01",
"job_summary": null,
"skills": [],
"interests": [],
"linkedin_username": "aaron-smith-0a072a22",
"linkedin_url": "linkedin.com/in/aaron-smith-0a072a22",
"linkedin_id": "79436210",
"linkedin_connections": null,
"facebook_username": "aaron.smith",
"facebook_url": "www.facebook.com/aaron.smith",
"facebook_id": "1573576309",
"twitter_username": null,
"twitter_url": null,
"github_username": "aaronsmith",
"github_url": "github.com/aaronsmith",
"profiles": [
{
"network": "linkedin",
"url": "linkedin.com/in/aaron-smith-0a072a22",
"username": "aaron-smith-0a072a22"
},
{
"network": "facebook",
"url": "facebook.com/aaron.smith",
"username": "aaron.smith"
},
{
"network": "github",
"url": "github.com/aaronsmith",
"username": "aaronsmith"
}
],
"linkedin_summary": null,
"education": [],
"experience": [],
"certificates": [],
"languages": []
},
"status": 200
}The bulk person enrichment endpoint works like the single enrichment endpoint. The same parameters and rules apply, however you can specify multiple people at once.
The request body should be JSON encoded.
curl -X POST https://www.nymeria.io/api/v4/person/enrich/bulk -H 'X-Api-Key: insert-api-key' -H 'Content-Type: application/json'{
"requests": [
{
"params": {
"email": "punksrus@yahoo.com"
},
"metadata": {
"notes": "This should be the Aaron guy."
}
},
{
"params": {
"profile": "linkedin.com/in/someone-that-does-not-exist"
}
}
]
}[
{
"data": {
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"first_name": "Aaron",
"last_name": "Smith",
"full_name": "Aaron Smith",
"gender": null,
"age": null,
"birth_year": null,
"birth_date": null,
"work_email": "aaron_smith@mastercard.com",
"personal_emails": [
"aaronsmith@gmail.com"
],
"emails": [
{
"type": "professional",
"name": "aaron_smith",
"domain": "mastercard.com",
"address": "aaron_smith@mastercard.com"
},
{
"type": "personal",
"name": "aaronksmith",
"domain": "gmail.com",
"address": "aaronsmith@gmail.com"
},
{
"type": "personal",
"name": "punksrus",
"domain": "yahoo.com",
"address": "punksrus@yahoo.com"
}
],
"mobile_phone": "+13362112012",
"phone_numbers": [
"+13362112012"
],
"industry": "Information Technology And Services",
"location_name": "Leander, Texas, United States",
"location_last_updated": "2020-10-01",
"location_country": "United States",
"inferred_years_of_experience": null,
"inferred_salary": null,
"job_title": "Senior Software Engineer",
"job_title_role": "Engineering",
"job_title_levels": [
"senior"
],
"job_start_date": "2019-11",
"job_company_name": "Clear Channel",
"job_company_website": null,
"job_company_founded": null,
"job_company_size": null,
"job_company_linkedin_url": null,
"job_last_updated": "2020-09-01",
"job_summary": null,
"skills": [],
"interests": [],
"linkedin_username": "aaron-smith-0a072a22",
"linkedin_url": "linkedin.com/in/aaron-smith-0a072a22",
"linkedin_id": "79436210",
"linkedin_connections": null,
"facebook_username": "aaron.smith",
"facebook_url": "www.facebook.com/aaron.smith",
"facebook_id": "1573576309",
"twitter_username": null,
"twitter_url": null,
"github_username": "aaronsmith",
"github_url": "github.com/aaronsmith",
"profiles": [
{
"network": "linkedin",
"url": "linkedin.com/in/aaron-smith-0a072a22",
"username": "aaron-smith-0a072a22"
},
{
"network": "facebook",
"url": "facebook.com/aaron.smith",
"username": "aaron.smith"
},
{
"network": "github",
"url": "github.com/aaronsmith",
"username": "aaronsmith"
}
],
"linkedin_summary": null,
"education": [],
"experience": [],
"certificates": [],
"languages": []
},
"metadata": {
"notes": "This should be the Aaron guy."
},
"status": 200
},
{
"error": {
"message": "No records were found matching ID: this-is-an-invalid-id",
"type": "not_found"
},
"status": 404
}
]This endpoint is useful if you want to display a preview of a person's information (for example, in a search result page). The input is the exact same as the enrichment endpoint, however only basic information and hints are returned.
Note, one credit is consumed for each successful preview.
curl https://www.nymeria.io/api/v4/person/enrich/preview?profile=linkedin.com/in/aaron-smith-0a072a22 -H "X-Api-Key: INSERT_API_KEY"{
"data": {
"birth_date": false,
"birth_year": false,
"certificates": false,
"education": false,
"emails": true,
"experience": false,
"facebook_id": true,
"facebook_url": true,
"facebook_username": true,
"first_name": "Aaron",
"full_name": "Aaron Smith",
"gender": false,
"github_url": true,
"github_username": true,
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"industry": true,
"inferred_salary": false,
"inferred_years_of_experience": false,
"interests": false,
"job_company_founded": false,
"job_company_linkedin_url": false,
"job_company_name": "Clear Channel",
"job_company_size": false,
"job_company_website": false,
"job_last_updated": true,
"job_start_date": true,
"job_summary": false,
"job_title": "Senior Software Engineer",
"job_title_levels": true,
"job_title_role": true,
"languages": false,
"last_name": "Smith",
"linkedin_connections": false,
"linkedin_id": true,
"linkedin_summary": false,
"linkedin_url": true,
"linkedin_username": true,
"location_country": true,
"location_last_updated": true,
"location_name": "Leander, Texas, United States",
"mobile_phone": true,
"personal_emails": true,
"phone_numbers": true,
"profiles": true,
"skills": false,
"twitter_url": false,
"twitter_username": false,
"work_email": true
},
"status": 200
}The search endpoint is useful when you have some information that is tied to someone but you lack specific information. The identification API can help identify possible candidates for the information you have.
The following query parameters are valid:
Optionally, you can provide a filter parameter or a require parameter to filter out certain kinds of data and require other kinds of data. For example, you can filter out professional email addresses and require an email address, phone number or personal email address.
At this time, the only valid filter parameter is professional-emails which can be used to filter out professional emails.
The require parameter has a number of valid values. You can require any of the following data points:
Note, you can use multiple requirements by separating them via a comma. For example, you can require an email and a phone number with require=email,phone.
You can use the limit parameter to limit the number of people returned. The default is 10. You can also use the offset parameter to walk through search results (default is 0).
A single credit is taken for each successful enrichment. If no additional information is returned in a request then no credit will be deducted. Furthermore, if the same data is returned within a 30 day window only a single credit is deducted.
Note, one credit is consumed for each person returned.
curl https://www.nymeria.io/api/v4/person/search?name=aaron%20smith&location=texas -H "X-Api-Key: INSERT_API_KEY"{
"data": [
{
"data": {
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"first_name": "Aaron",
"last_name": "Smith",
"full_name": "Aaron Smith",
"gender": null,
"age": null,
"birth_year": null,
"birth_date": null,
"work_email": "aaron_smith@mastercard.com",
"personal_emails": [
"aaronsmith@gmail.com"
],
"emails": [
{
"type": "professional",
"name": "aaron_smith",
"domain": "mastercard.com",
"address": "aaron_smith@mastercard.com"
},
{
"type": "personal",
"name": "aaronksmith",
"domain": "gmail.com",
"address": "aaronsmith@gmail.com"
},
{
"type": "personal",
"name": "punksrus",
"domain": "yahoo.com",
"address": "punksrus@yahoo.com"
}
],
"mobile_phone": "+13362112012",
"phone_numbers": [
"+13362112012"
],
"industry": "Information Technology And Services",
"location_name": "Leander, Texas, United States",
"location_last_updated": "2020-10-01",
"location_country": "United States",
"inferred_years_of_experience": null,
"inferred_salary": null,
"job_title": "Senior Software Engineer",
"job_title_role": "Engineering",
"job_title_levels": [
"senior"
],
"job_start_date": "2019-11",
"job_company_name": "Clear Channel",
"job_company_website": null,
"job_company_founded": null,
"job_company_size": null,
"job_company_linkedin_url": null,
"job_last_updated": "2020-09-01",
"job_summary": null,
"skills": [],
"interests": [],
"linkedin_username": "aaron-smith-0a072a22",
"linkedin_url": "linkedin.com/in/aaron-smith-0a072a22",
"linkedin_id": "79436210",
"linkedin_connections": null,
"facebook_username": "aaron.smith",
"facebook_url": "www.facebook.com/aaron.smith",
"facebook_id": "1573576309",
"twitter_username": null,
"twitter_url": null,
"github_username": "aaronsmith",
"github_url": "github.com/aaronsmith",
"profiles": [
{
"network": "linkedin",
"url": "linkedin.com/in/aaron-smith-0a072a22",
"username": "aaron-smith-0a072a22"
},
{
"network": "facebook",
"url": "facebook.com/aaron.smith",
"username": "aaron.smith"
},
{
"network": "github",
"url": "github.com/aaronsmith",
"username": "aaronsmith"
}
],
"linkedin_summary": null,
"education": [],
"experience": [],
"certificates": [],
"languages": []
},
"metadata": {
"notes": "This should be the Aaron guy."
},
"status": 200
}
],
"status": 200,
"total": 21
}If you have an id for a Nymeria person you can use the retrieve endpoint to pull complete person information including their contact details.
Note, one credit is consumed for each successful retrieval.
curl https://www.nymeria.io/api/v4/person/retrieve/23864a9f-4cea-4c1c-b51e-0b15c9a5203c -H "X-Api-Key: INSERT_API_KEY"{
"data": {
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"first_name": "Aaron",
"last_name": "Smith",
"full_name": "Aaron Smith",
"gender": null,
"age": null,
"birth_year": null,
"birth_date": null,
"work_email": "aaron_smith@mastercard.com",
"personal_emails": [
"aaronsmith@gmail.com"
],
"emails": [
{
"type": "professional",
"name": "aaron_smith",
"domain": "mastercard.com",
"address": "aaron_smith@mastercard.com"
},
{
"type": "personal",
"name": "aaronksmith",
"domain": "gmail.com",
"address": "aaronsmith@gmail.com"
},
{
"type": "personal",
"name": "punksrus",
"domain": "yahoo.com",
"address": "punksrus@yahoo.com"
}
],
"mobile_phone": "+13362112012",
"phone_numbers": [
"+13362112012"
],
"industry": "Information Technology And Services",
"location_name": "Leander, Texas, United States",
"location_last_updated": "2020-10-01",
"location_country": "United States",
"inferred_years_of_experience": null,
"inferred_salary": null,
"job_title": "Senior Software Engineer",
"job_title_role": "Engineering",
"job_title_levels": [
"senior"
],
"job_start_date": "2019-11",
"job_company_name": "Clear Channel",
"job_company_website": null,
"job_company_founded": null,
"job_company_size": null,
"job_company_linkedin_url": null,
"job_last_updated": "2020-09-01",
"job_summary": null,
"skills": [],
"interests": [],
"linkedin_username": "aaron-smith-0a072a22",
"linkedin_url": "linkedin.com/in/aaron-smith-0a072a22",
"linkedin_id": "79436210",
"linkedin_connections": null,
"facebook_username": "aaron.smith",
"facebook_url": "www.facebook.com/aaron.smith",
"facebook_id": "1573576309",
"twitter_username": null,
"twitter_url": null,
"github_username": "aaronsmith",
"github_url": "github.com/aaronsmith",
"profiles": [
{
"network": "linkedin",
"url": "linkedin.com/in/aaron-smith-0a072a22",
"username": "aaron-smith-0a072a22"
},
{
"network": "facebook",
"url": "facebook.com/aaron.smith",
"username": "aaron.smith"
},
{
"network": "github",
"url": "github.com/aaronsmith",
"username": "aaronsmith"
}
],
"linkedin_summary": null,
"education": [],
"experience": [],
"certificates": [],
"languages": []
},
"metadata": {
"notes": "This should be the Aaron guy."
},
"status": 200
}The bulk retrieve endpoint works the same way as the single retrieve endpoint but allows you to enter any number of ids. The request body should be JSON encoded.
curl -X POST https://www.nymeria.io/api/v4/person/retrieve/bulk -H 'X-Api-Key: INSERT_API_KEY' -H 'Content-Type: application/json'{
"requests": [
{
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"metadata": {
"notes": "This should be the Aaron guy."
}
},
{
"id": "this-is-an-invalid-id"
}
]
}[
{
"data": {
"id": "01c14d88-a7c1-428d-9423-fa44357029f4",
"first_name": "Aaron",
"last_name": "Smith",
"full_name": "Aaron Smith",
"gender": null,
"age": null,
"birth_year": null,
"birth_date": null,
"work_email": "aaron_smith@mastercard.com",
"personal_emails": [
"aaronsmith@gmail.com"
],
"emails": [
{
"type": "professional",
"name": "aaron_smith",
"domain": "mastercard.com",
"address": "aaron_smith@mastercard.com"
},
{
"type": "personal",
"name": "aaronksmith",
"domain": "gmail.com",
"address": "aaronsmith@gmail.com"
},
{
"type": "personal",
"name": "punksrus",
"domain": "yahoo.com",
"address": "punksrus@yahoo.com"
}
],
"mobile_phone": "+13362112012",
"phone_numbers": [
"+13362112012"
],
"industry": "Information Technology And Services",
"location_name": "Leander, Texas, United States",
"location_last_updated": "2020-10-01",
"location_country": "United States",
"inferred_years_of_experience": null,
"inferred_salary": null,
"job_title": "Senior Software Engineer",
"job_title_role": "Engineering",
"job_title_levels": [
"senior"
],
"job_start_date": "2019-11",
"job_company_name": "Clear Channel",
"job_company_website": null,
"job_company_founded": null,
"job_company_size": null,
"job_company_linkedin_url": null,
"job_last_updated": "2020-09-01",
"job_summary": null,
"skills": [],
"interests": [],
"linkedin_username": "aaron-smith-0a072a22",
"linkedin_url": "linkedin.com/in/aaron-smith-0a072a22",
"linkedin_id": "79436210",
"linkedin_connections": null,
"facebook_username": "aaron.smith",
"facebook_url": "www.facebook.com/aaron.smith",
"facebook_id": "1573576309",
"twitter_username": null,
"twitter_url": null,
"github_username": "aaronsmith",
"github_url": "github.com/aaronsmith",
"profiles": [
{
"network": "linkedin",
"url": "linkedin.com/in/aaron-smith-0a072a22",
"username": "aaron-smith-0a072a22"
},
{
"network": "facebook",
"url": "facebook.com/aaron.smith",
"username": "aaron.smith"
},
{
"network": "github",
"url": "github.com/aaronsmith",
"username": "aaronsmith"
}
],
"linkedin_summary": null,
"education": [],
"experience": [],
"certificates": [],
"languages": []
},
"metadata": {
"notes": "This should be the Aaron guy."
},
"status": 200
},
{
"error": {
"message": "No records were found matching ID: this-is-an-invalid-id",
"type": "not_found"
},
"status": 404
}
]The company enrichment endpoint is used to locate additional information about companies.
The following are valid query parameters:
Note, one credit is consumed for each successful enrichment.
curl https://www.nymeria.io/api/v4/company/enrich?website=nymeria.io -H "X-Api-Key: INSERT_API_KEY"{
"data": {
"id": "4fe5ec89-3b72-4993-9375-e8c8ee162f07",
"employee_count_from": 1,
"employee_count_to": 10,
"size": "1-10",
"name": "Nymeria",
"industry": "Computer Software",
"founded": 2017,
"website_url": "nymeria.io",
"linkedin_id": "19213208",
"linkedin_name": "nymeria",
"twitter_name": null,
"facebook_name": null,
"location_country": "United States",
"location_geo": "37.67,-113.06",
"location_continent": "North America",
"location_locality": "Cedar City",
"location_name": "Cedar City, Utah, United States",
"location_region": "Utah",
"updated_at": "10/31/2022"
},
"status": 200
}The company search endpoint is used to do broad searches for multiple companies that fit supplied criteria.
The following query parameters are valid:
You can use the limit parameter to limit the number of people returned. The default is 10. You can also use the offset parameter to walk through search results (default is 0).
Note, one credit is consumed for each company that is returned.
curl https://www.nymeria.io/api/v4/company/search?query="(name:Microsoft*%20||%20name:Tesla)%20&&%20industry:*Technology*"&size=4 -H "X-Api-Key: INSERT_API_KEY"{
"data": [
{
"id": "01897f9c-8784-4b59-a404-ee797c91e59d",
"employee_count_from": 1,
"employee_count_to": 10,
"size": "1-10",
"name": "Microsoft For Startups India",
"industry": "Information Technology And Services",
"founded": 2011,
"website_url": null,
"linkedin_id": "14443672",
"linkedin_name": "microsoft-for-start-ups-india",
"twitter_name": null,
"facebook_name": null,
"location_country": "India",
"location_geo": "12.98,77.58",
"location_continent": "Asia",
"location_locality": "Bangalore",
"location_name": "Bangalore, Karnataka, India",
"location_region": "Karnataka",
"updated_at": "10/31/2022"
},
{
"id": "06b4ce01-0e03-4a43-ac81-d572382d2598",
"employee_count_from": 11,
"employee_count_to": 50,
"size": "11-50",
"name": "Microsoft Innovation Center Armenia",
"industry": "Information Technology And Services",
"founded": 2011,
"website_url": "mic.am",
"linkedin_id": "13313526",
"linkedin_name": "microsoftinnovationcenterarmenia",
"twitter_name": null,
"facebook_name": null,
"location_country": "Armenia",
"location_geo": null,
"location_continent": "Asia",
"location_locality": null,
"location_name": "Yerevan, Armenia",
"location_region": "Yerevan",
"updated_at": "10/31/2022"
},
{
"id": "0ad619d9-4efc-466d-ae39-93e63a2f6115",
"employee_count_from": 1,
"employee_count_to": 10,
"size": "1-10",
"name": "Microsoft Licensing",
"industry": "Information Technology And Services",
"founded": 2013,
"website_url": "nevadaitsolutions.com",
"linkedin_id": "2050778",
"linkedin_name": "microsoft-licensing",
"twitter_name": "nevadaitsolutio",
"facebook_name": "nevadaitsolutions",
"location_country": "United States",
"location_geo": "39.52,-119.81",
"location_continent": "North America",
"location_locality": "Reno",
"location_name": "Reno, Nevada, United States",
"location_region": "Nevada",
"updated_at": "10/31/2022"
},
{
"id": "17f2e083-31e4-404f-bc51-73dd6e76666f",
"employee_count_from": 51,
"employee_count_to": 200,
"size": "51-200",
"name": "Tesla",
"industry": "Information Technology And Services",
"founded": 1995,
"website_url": null,
"linkedin_id": "269979",
"linkedin_name": "teslabrasil",
"twitter_name": null,
"facebook_name": "tesla.com.br",
"location_country": "Brazil",
"location_geo": null,
"location_continent": "South America",
"location_locality": null,
"location_name": "Brazil",
"location_region": null,
"updated_at": "10/31/2022"
}
],
"status": 200,
"total": 35
}The verify endpoint can be used to verify email addresses. Note, all emails found using Nymeria are verified and there is no need to verify emails you found with Nymeria. However, if you have external emails you would like to verify you can leverage the email verification API to do so.
The only parameter required for the verify endpoint is email. Note, each request will consume one credit.
curl https://www.nymeria.io/api/v4/email/verify?email=demo@nymeria.io -H "X-Api-Key: INSERT_API_KEY"{
"data": {
"result": "valid",
"flags": [
"has_dns",
"has_dns_mx"
],
"suggested_correction": "",
"execution_time": 1201
},
"status": 200
}The bulk verification endpoint works the same way as the single verification endpoint but allows you to enter any number of emails. The request body should be JSON encoded.
curl -X POST https://www.nymeria.io/api/v4/email/verify/bulk -H "X-Api-Key: INSERT_API_KEY" -H 'Content-Type: application/json'{
"requests": [
{
"params": {
"email": "someone@yahoo.com"
},
"metadata": {
"notes": "This should be someone at Yahoo."
}
},
{
"params": {
"email": "someone@nymeria.io"
},
"metadata": {
"notes": "Me."
}
},
{
"email": "this-is-an-invalid-email"
}
]
} [
{
"data": {
"result": "valid",
"flags": [
"has_dns",
"has_dns_mx",
"connect_success"
],
"suggested_correction": "",
"execution_time": 1201
},
"metadata": {
"notes": "This should be someone at Yahoo."
},
"status": 200
},
{
"data": {
"result": "valid",
"flags": [
"has_dns",
"has_dns_mx",
"connect_success"
],
"suggested_correction": "",
"execution_time": 1201
},
"metadata": {
"notes": "Me."
},
"status": 200
}
]