Developers

API


If you have a Nymeria account you can leverage our public API. You will need to generate an API key first. You can do so via the API page. We do offer a number of libraries and SDKs for use as well. You can find them on our Github page.


Responses

Nymeria's API is a JSON based API. All successful API responses contain a status code of 200, and a JSON body. The basic JSON response envelope looks like the following:

{
  "data": {},
  "status": "success"
}

The status message in the response can be used to determine if the call was successfully handled, and the data field can be safely processed. If the server responds with a non-successful error code such as a 500 then no JSON data will be returned.


Ratelimit

All API requests to 10 requests per-second. A 503 will be returned if you hit the ratelimit. If you need to perform additional requests or perform actions in a higher volume please reach out.


Authentication

All API endpoints require an API key. The key can be sent a number of ways:

  • As a form field or query parameter named: api_key
  • As a header named: X-Api-Key

Note, all API endpoints support both GET and POST methods for your convenience and to provide a wider ranger of support for different clients. However, you need to use the appropriate parameters for each method. If you use the GET method you need to use query parameters, and if you use the POST method you should use form data.

To check your API key and verify your authentication, you can do the following (using cURL):

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."
  }
}


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".

curl -X POST https://www.nymeria.io/api/v3/verify -d api_key=<insert-api-key> -d email=demo@nymeria.io

Each request will consume a single API credit.

{
  "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"
    ]
  },
}


Enrichment

A url, identifier or 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).

Check the examples below to see how urls and identifiers can be used.

Enrich via a url parameter

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"
      }
    ]
  }
}

Enrich via an email

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"
      }
    ]
  }
}

Enrich via an identifier parameter

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"
      }
    ]
  }
}

A credit is deducted if the request returns any data from our service. If no contact data is found, the resulting fields will be empty and the status message will read "failure". No credit is deducted if the status read failure.


Bulk 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"}]

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"
                    }
                ]
            }
        }
    ]
}

Note, each successful enrichment will deduct one credit. If your account runs out of credit any remaining records will not be processed.

People

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.

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"
      ]
    },
    // ...
  ]
}

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).

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"
      }
    },
    // ...
  ]
}

Each unlocked person will consume one credit.

The best contact finder, period.
Nymeria

© 2022 - Nymeria, LLC