Developer Documentation

The Nymeria API is a REST interface for enriching and searching people and company records. Send what you know — a profile URL, an email address, a company name — and get back the full record, including verified work emails, personal emails and mobile phone numbers. A credit is consumed only when a record is returned; a 404 costs nothing.

Authentication

All requests authenticate with an API key passed in the X-API-Key header. Keys are managed from your account dashboard. A single key covers every endpoint.

X-API-Key: YOUR_API_KEY

Treat the key like a password: it grants access to the full credit balance of the account. Rotate it from the dashboard if it leaks. Never ship it in browser-side code — proxy requests through your own backend.

Quickstart

Enrich a person from a LinkedIn profile URL. This is the smallest complete request:

curl "https://www.nymeria.io/api/v4/person/enrich?profile=linkedin.com/in/wozniaksteve" \
    -H "X-API-Key: YOUR_API_KEY"

A successful response:

{
  "status": 200,
  "data": {
    "id": "ba50dc94-b163-4b0a-a21a-f5c9e8591af6",
    "first_name": "steve",
    "last_name": "wozniak",
    "full_name": "steve wozniak",
    "industry": "computers and electronics manufacturing",
    "location_name": "los gatos, california",
    "location_country": "united states",
    "job_title": "chief scientist",
    "job_company_name": "fusion-io",
    "linkedin_username": "wozniaksteve",
    "linkedin_url": "https://www.linkedin.com/in/wozniaksteve",
    "work_email": "xxxxxxxxxxx@woz.org",
    "personal_emails": ["xxxxxxxxxxx@yahoo.com"],
    "emails": [
      {
        "type": "professional",
        "name": "xxxxxxxxxxx",
        "domain": "woz.org",
        "address": "xxxxxxxxxxx@woz.org"
      }
    ],
    "mobile_phone": "+1 xxxxxxxxxxx",
    "phone_numbers": ["+1 xxxxxxxxxxx"],
    "profiles": [
      {
        "network": "linkedin",
        "url": "https://www.linkedin.com/in/wozniaksteve",
        "username": "wozniaksteve"
      }
    ]
  }
}

Fields that are unknown for a record are returned as null (or an empty array) rather than omitted, so parsing stays uniform. If nobody matches, the response is a 404 and no credit is consumed.

Person Enrichment

Takes a social media profile URL, LinkedIn identifier, or an email address and returns the matching person's profile with contact information. Contact information means a personal email, work email, or phone number.

The endpoint expects one of the following query parameters:

More than one parameter may be given. The first parameter that matches a person will be used. A successful enrichment consumes 1 credit; a 404 consumes none.

Person Search

Searches people by attributes — name fragments, title, company, location — and returns paginated person records in the same shape as enrichment responses.

curl "https://www.nymeria.io/api/v4/person/search?first_name=steve&last_name=wozniak&limit=10&offset=0" \
    -H "X-API-Key: YOUR_API_KEY"

A successful response:

{
  "data": [
    {
      "emails": [
        {
          "address": "xxxxxxxxx@woz.org",
          "domain": "woz.org",
          "name": "xxxxxxxxx",
          "type": "professional"
        }
      ],
      "first_name": "steve",
      "full_name": "steve wozniak",
      "id": "ba50dc94-b163-4b0a-a21a-f5c9e8591af6",
      "industry": "computers and electronics manufacturing",
      "job_company_name": "fusion-io",
      "job_title": "chief scientist",
      "last_name": "wozniak",
      "linkedin_url": "https://www.linkedin.com/in/wozniaksteve",
      "linkedin_username": "wozniaksteve",
      "location_country": "united states",
      "location_name": "los gatos, california",
      "mobile_phone": "+1 xxxxxxxxx",
      "personal_emails": ["xxxxxxxxx@yahoo.com"],
      "phone_numbers": ["+1 xxxxxxxxx"],
      "profiles": [
        {
          "network": "linkedin",
          "url": "https://www.linkedin.com/in/wozniaksteve",
          "username": "wozniaksteve"
        }
      ],
      "work_email": "xxxxxxxxx@woz.org"
    }
  ],
  "meta": {
    "first_name": "steve",
    "last_name": "wozniak",
    "limit": 1,
    "location": "los gatos, california",
    "offset": 0
  },
  "status": 200
}

Pagination is controlled with limit and offset. One credit is consumed for each person returned — paginate deliberately. If no people are found, an empty result list will be returned and no credit will be consumed.

Company Enrichment

Takes enrichment parameters such as a company's name or website URL and returns the matching company profile — useful for filling in missing firmographics.

More than one parameter may be given; the first that matches a company is used. If no company is matched, a 404 is returned and no credit is consumed. If a company is returned, 1 credit is consumed.

A successful response:

{
  "status": 200,
  "data": {
    "uuid": "fe6ad720-8c76-45c5-a794-1c92cfea6270",
    "name": "nymeria",
    "url": "nymeria.io",
    "size": "1-10",
    "founded": "2017",
    "industry": "computer software",
    "location": "cedar city, utah",
    "country": "united states",
    "linkedin_id": 19213208,
    "linkedin_url": "linkedin.com/company/nymeria"
  }
}

Company Search

Searches companies by attributes and returns paginated company records in the same shape as company enrichment responses. As with person search, limit and offset control pagination and one credit is consumed per company returned. An empty result set costs nothing.

Takes search parameters such as a company's name or website URL and returns the matching company profile — useful for filling in missing firmographics.

A successful response:

{
  "data": [
    {
      "country": "united states",
      "founded": "2017",
      "industry": "computer software",
      "linkedin_id": 19213208,
      "linkedin_url": "linkedin.com/company/nymeria",
      "location": "cedar city, utah",
      "name": "nymeria",
      "size": "1-10",
      "url": "nymeria.io",
      "uuid": "fe6ad720-8c76-45c5-a794-1c92cfea6270"
    }
  ],
  "meta": {
    "limit": 1,
    "name": "nymeria",
    "offset": 0
  },
  "status": 200,
  "total": 1
}

Require Filters

Every enrichment call accepts a require parameter restricting what counts as a billable match. If the matched record lacks the required contact type, the API returns a 404 instead of a record you can't use — and no credit moves.

curl "https://www.nymeria.io/api/v4/person/enrich?profile=linkedin.com/in/wozniaksteve&require=professional-email" \
    -H "X-API-Key: YOUR_API_KEY"

Credit Usage

The API uses a simple credit system. One credit equals one enriched or returned record:

• Person Enrichment — 1 credit per person enriched.
• Person Search — 1 credit per person in the result.
• Company Enrichment — 1 credit per company enriched.
• Company Search — 1 credit per company returned.

Credits are granted in full at the start of your plan's period and can be spent at any point while the plan is active. Unmatched lookups and unmet require filters never consume credits.

Response Headers

Every billable response reports credit usage in its headers, so clients can track the running balance without a separate accounting call:

X-Call-Credits-Spent: 1
 X-Call-Credits-Type: enrichment
 X-Total-Limit-Remaining: 299

Log X-Total-Limit-Remaining alongside request telemetry — it is the cheapest way to detect runaway loops before they exhaust your balance.

Errors

Errors are returned as JSON with a non-2xx status. They echo back the original params and any metadata attached to the request, which keeps retry logic simple — you always know which request failed and why.

The important asymmetry: only a 200 spends a credit. Retry on 429 and 500 without worrying about double-billing — a retry of the same enrichment costs nothing unless it succeeds.