API Reference

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.

SDKs

If you are interested in one of our officially supported SDKs you can find them here along with a number of example projects using the Nymeria SDKs. Currently, we support Ruby, Go, Python and JavaScript SDKs.


Authentication

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.

Test Authentication

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/v3/check-authentication -d api_key=<insert-api-key>
{
  "status": "success",
  "data": {
    "message": "Great! You have successfully authenticated with the API."
  }
}

People Enrichment

A url, identifier or an email parameter can be used to enrich a profile with contact and biographic information. A URL from any supported website is acceptable. These include profile links for sites like LinkedIn, Github, Twitter, Facebook, etc. For more specific identifiers, the identifier parameter can be used. Currently, the following identifiers exist:

  • fid which is for Facebook IDs (numeric IDs).
  • lid which is for Linkedin IDs (numeric IDs).

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:

  • email will only return data if any emails are present.
  • phone will only return data if a phone number is present.
  • professional-email will only return data if a professional email is present.
  • personal-email will only return data if a personal email is present.

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.

Enrichment Response

Here's an example using a URL for people enrichment. This example uses a GitHub profile link, but Nymeria also supports finding emails for other social media links such as Twitter, Facebook and LinkedIn.

curl https://www.nymeria.io/api/v3/enrich -d api_key=<insert-api-key> -d url=github.com/dhh
{
  "status": "success",
  "meta": {
    "url": "github.com/dhh",
    "identifier": null
  },
  "usage": {
    "used": 38,
    "limit": 300
  },
  "data": {
    "bio": {
      "first_name": "David",
      "last_name": "Hansson",
      "company": "Basecamp",
      "company_website": "basecamp.com",
      "job_last_updated": "2017-06-02",
      "location_last_updated": "2017-02-01"
    },
    "emails": [
      {
      "type": "professional",
      "name": "david",
      "domain": "loudthinking.com",
      "address": "david@loudthinking.com"
      }
      ],
      "phone_numbers": [],
      "social": [
      {
      "type": "github",
      "id": "dhh",
      "url": "https://github.com/dhh"
      },
      {
      "type": "gravatar",
      "id": "ed9635566b34ade32274f510f0f9a6d2",
      "url": "http://gravatar.com/webster132"
      }
    ]
  }
}

Here's an example using an email address to locate additional contact information (or update biographic and social information).

curl https://www.nymeria.io/api/v3/enrich -d api_key=<insert-api-key> -d email=david@loudthinking.com
{
  "status": "success",
  "meta": {
    "url": "github.com/dhh",
    "identifier": null
  },
  "usage": {
    "used": 38,
    "limit": 300
  },
  "data": {
    "bio": {
      "first_name": "David",
      "last_name": "Hansson",
      "company": "Basecamp",
      "company_website": "basecamp.com",
      "job_last_updated": "2017-06-02",
      "location_last_updated": "2017-02-01"
    },
    "emails": [
      {
      "type": "professional",
      "name": "david",
      "domain": "loudthinking.com",
      "address": "david@loudthinking.com"
      }
      ],
      "phone_numbers": [],
      "social": [
      {
      "type": "github",
      "id": "dhh",
      "url": "https://github.com/dhh"
      },
      {
      "type": "gravatar",
      "id": "ed9635566b34ade32274f510f0f9a6d2",
      "url": "http://gravatar.com/webster132"
      }
    ]
  }
}

Here's an example using an identifier to locate additional contact information.

curl https://www.nymeria.io/api/v3/enrich -d api_key=<insert-api-key> -d identifier=fid:693583293
{
  "status": "success",
  "developer_message": "",
  "meta": {
    "url": null,
    "identifier": "fid:693583293"
  },
  "usage": {
    "used": 39,
    "limit": 300
  },
  "data": {
    "bio": {
      "first_name": "Kyla",
      "last_name": "Myers",
      "title": "Vice President",
      "company": "International Cake Exploration Society",
      "company_website": "ices.org",
      "job_last_updated": "2017-06-02",
      "location_last_updated": "2017-02-01"
    },
    "emails": [
      {
        "type": "personal",
        "name": "kyla_kae",
        "domain": "yahoo.com",
        "address": "kyla_kae@yahoo.com"
      }
    ],
    "phone_numbers": [
      {
        "number": "15126986642"
      }
    ],
    "social": [
      {
        "type": "linkedin",
        "id": "kylamyers",
        "url": "https://www.linkedin.com/in/kylamyers"
      },
      {
        "type": "facebook",
        "id": "kylakae",
        "url": "https://facebook.com/kylakae"
      }
    ]
  }
}

Bulk People Enrichment

Multiple enrichment calls can be made in batch. You can send up to 10,000 records at a time with the bulk enrichment endpoint. The format for the request is JSON based. The parameters required are the same as the single enrichment endpoint above. The JSON format for the request body looks like the following:

[{"url": "github.com/dhh"}, {"url": "linkedin.com/in/wozniaksteve"}, {"identifier": "fid:693583293"}]

You can optionally provide a custom field if you need to correlate the responses back to your own system.

[{"custom": { "id": "some-id" }, "url": "linkedin.com/in/wozniaksteve"}]

Bulk Enrichment Response

The bulk enrichment endpoint is only available via a POST request with a JSON body and content type. Here's an example:

curl -X POST https://www.nymeria.io/api/v3/bulk-enrich -H 'X-Api-Key: insert-api-key' -H 'Content-Type: application/json' -d '{ "people": [{"url":"github.com/dhh"}, {"url": "linkedin.com/in/wozniaksteve"}] }'
{
    "status": "success",
    "usage": {
        "limit": 100,
        "used": 47
    },
    "data": [
        {
            "meta": {
                "custom": null,
                "identifier": "",
                "url": "github.com/dhh"
            },
            "result": {
                "bio": {
                    "company": "Basecamp",
                    "company_website": "basecamp.com",
                    "first_name": "David",
                    "last_name": "Hansson",
                    "job_last_updated": "2018-07-02",
                    "location_last_updated": "2016-02-01"
                },
                "emails": [
                    {
                        "address": "david@loudthinking.com",
                        "domain": "loudthinking.com",
                        "name": "david",
                        "type": "professional"
                    }
                ],
                "phone_numbers": [],
                "social": [
                    {
                        "id": "dhh",
                        "type": "github",
                        "url": "https://github.com/dhh"
                    },
                    {
                        "id": "ed9635566b34ade32274f510f0f9a6d2",
                        "type": "gravatar",
                        "url": "http://gravatar.com/webster132"
                    }
                ]
            }
        },
        {
            "meta": {
                "custom": null,
                "identifier": "",
                "url": "linkedin.com/in/wozniaksteve"
            },
            "result": {
                "bio": {
                    "company": "Sandisk",
                    "company_website": "sandisk.com",
                    "first_name": "Steve",
                    "last_name": "Wozniak",
                    "title": "Chief Scientist",
                    "job_last_updated": "2020-12-02",
                    "location_last_updated": "2018-10-01"
                },
                "emails": [
                    {
                        "address": "steve@woz.org",
                        "domain": "woz.org",
                        "name": "steve",
                        "type": "professional"
                    }
                ],
                "phone_numbers": [],
                "social": [
                    {
                        "id": "wozniaksteve",
                        "type": "linkedin",
                        "url": "https://www.linkedin.com/in/wozniaksteve"
                    }
                ]
            }
        }
    ]
}

People Search

The people API is used to search for people. You can search using query parameters and filters. You can search via:

  • q is a general key word search parameter. Will match fields such as a person's name, title, company, skills, etc.
  • location a location (city, state, etc).
  • country a country to require.
  • company a company name to match.
  • title a job title to match.
  • first_name a person's first name.
  • last_name a person's last name.
  • skills a comma separated list of skills that are required.
  • has_email if "true" will only return people with email address.
  • has_phone if "true" will only return people with phone numbers.

Search Response

curl https://www.nymeria.io/api/v3/people?skills=Ruby+on+Rails&location=Palo+Alto -H 'X-Api-Key: insert-api-key'
{
  "status": "success",
  "meta": {
    "query": {
      "rows": 10,
      "start": 0,
      "skills": [
        "Ruby on RAILS"
      ],
      "location": "Palo Alto"
    },
    "results": {
      "total": 237863
    }
  },
  "data": [
    {
      "uuid": "72b9ee55-3a18-4281-b4b3-de723d73123d",
      "first_name": "Ashley",
      "last_name": "Woz",
      "title": "Freelance Software Developer",
      "location": "Palo Alto, California",
      "country": "United States",
      "available_data": [
        "email",
        "phone",
        "facebook",
        "foursquare",
        "github",
        "gravatar",
        "linkedin",
        "stackoverflow",
        "twitter",
        "youtube"
      ]
    },
    {
      "uuid": "c06bb8f1-eafb-417f-813a-825eb00a2c06",
      "first_name": "Owen",
      "last_name": "Price",
      "title": "Software Engineer",
      "company": "Actblue Technical Services",
      "location": "Palo Alto, California",
      "country": "United States",
      "available_data": [
        "email",
        "phone",
        "linkedin"
      ]
    },
    {
      "uuid": "f50f21ad-5b46-45d3-aa6a-1f871a55ad77",
      "first_name": "John",
      "last_name": "Vernon",
      "title": "Engineering Development Manager",
      "company": "2600hz",
      "location": "Palo Alto, California",
      "country": "United States",
      "available_data": [
        "email",
        "phone",
        "facebook",
        "github",
        "linkedin",
        "twitter"
      ]
    },
    // ...
  ]
}

People Unlock

You can perform search queries without consuming credits. A credit will be consumed for each result you want to unlock. You can unlock a result by sending the uuids to the search endpoint (POST method).

Unlock Response

curl -X POST https://www.nymeria.io/api/v3/people -H 'X-Api-Key: insert-api-key' -H 'Content-Type: application/json' -d '{ "uuids": ["abc-123-456", "dev-123-456"] }'
{
  "status": "success",
  "meta": {
    "ids": [
      "72b9ee55-3a18-4281-b4b3-de723d73123d",
      "f50f21ad-5b46-45d3-aa6a-1f871a55ad77",
      "c06bb8f1-eafb-417f-813a-825eb00a2c06",
    ]
  },
  "usage": {
    "used": 5,
    "limit": 100
  },
  "data": [
    {
      "uuid": "72b9ee55-3a18-4281-b4b3-de723d73123d",
      "emails": [
        {
          "type": "personal",
          "name": "ashwoz",
          "domain": "gmail.com",
          "address": "ashwoz@gmail.com"
        },
        {
          "type": "professional",
          "name": "ashwoz",
          "domain": "oversee.net",
          "address": "ashwoz@oversee.net"
        }
      ],
      "phone_numbers": [
        {
          "number": "+13116371290"
        },
        {
          "number": "+13156370187"
        }
      ],
      "social": [
        {
          "type": "linkedin",
          "id": "ashwoz",
          "url": "https://www.linkedin.com/in/ashwoz"
        },
        {
          "type": "twitter",
          "id": "ashwoz",
          "url": "https://twitter.com/ashwoz"
        },
        {
          "type": "facebook",
          "id": "ashwoz",
          "url": "https://www.facebook.com/ashwoz"
        },
        {
          "type": "github",
          "id": "ashwoz",
          "url": "https://github.com/ashwoz"
        },
        {
          "type": "stackoverflow",
          "url": "https://stackoverflow.com/users/122059"
        },
        {
          "type": "youtube",
          "id": "ashwoz",
          "url": "https://youtube.com/user/ashwoz"
        },
        {
          "type": "gravatar",
          "id": "ashwoz",
          "url": "https://gravatar.com/ashwoz"
        },
        {
          "type": "foursquare",
          "id": "1914589",
          "url": "https://foursquare.com/user/1945859"
        }
      ],
      "bio": {
        "first_name": "Ashley",
        "last_name": "Woz",
        "title": "Freelance Software Developer",
        "location": "Palo Alto, California",
        "country": "United States",
        "job_last_updated": "2017-06-02",
        "location_last_updated": "2017-02-01"
      }
    },
    // ...
  ]
}

Email Verification

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.

API Reference

curl -X POST https://www.nymeria.io/api/v3/verify -d api_key=<insert-api-key> -d email=demo@nymeria.io
{
  "status": "success"
  "requests_used": 43,
  "request_limit": 1000,
  "data": {
    "meta": {
      "email": "demo@nymeria.io"
    },
    "result": "valid",
    "tags": [
      "has_dns_mx",
      "smtp_connectable",
      "smtp_accepted_email"
    ]
  }
}