Letrics | API Documentation

Introduction

You can integrate our service's data with our simple JSON API:

Contacts returns emails and profiles matching input criteria.
Companies returns companies matching input criteria.

Structure

Our API is designed to be as simple to use as possible. We always use the same basic structure:

data contains the data you requested.
meta provides information regarding your request.
errors shows errors with insights regarding what made the request fail.

Successful response

{
  "data": {
    ...
  },
  "meta": {
    ...
  }
}

Error response

{
  "errors": {
    ...
  }
}

Authentication

Every request to our API requires authentication with a key. Include the key via the Authorization header in your request:

Header format: Authorization: Bearer YOUR_API_KEY.
Missing/invalid key returns 401 Unauthorized.
Tokens are managed in user settings under API tokens.

Errors

When a request fails, the API returns an errors array. Each item includes an identifier, HTTP code, and a human-readable description.

id is a stable error identifier (for example invalid_input).
code is the HTTP status code for the failure (for example 400).
details explains what went wrong and how to fix the request.

Error example

{
  "errors": [
    {
      "id": "invalid_input",
      "code": 400,
      "details": "Invalid input values: added_after=not-a-date"
    }
  ]
}

Contacts

Returns contacts filtered by contact and company attributes.

Array filters support exclusions with the same field name prefixed by exclude_. For example, send industries to include industries and exclude_industries to omit them from the results.

Request Fields

Field	Type	Description
`job_titles`	array[string]	Case-insensitive partial contact job title matches (for example `manager` matches `Finance Manager`).
`departments`	array[string]	Exact contact department matches.
`seniorities`	array[string]	Exact contact seniority matches.
`has_personal_email`	boolean	When true, only contacts with a personal email are returned.
`has_linkedin_profile`	boolean	When true, only contacts with a LinkedIn profile are returned.
`is_decision_maker`	boolean	When true, only contacts marked as decision makers are returned.
`company_has_generic_email`	boolean	When true, only contacts whose company has at least one generic email are returned.
`company_has_linkedin_profile`	boolean	When true, only contacts whose company has a LinkedIn profile are returned.
`added_after`	string (UTC ISO8601)	Only contacts whose company was added to Letrics at or after this timestamp.
`added_before`	string (UTC ISO8601)	Only contacts whose company was added to Letrics at or before this timestamp.
`first_seen_after`	string (UTC ISO8601)	Only contacts whose company activity was first detected at or after this timestamp.
`first_seen_before`	string (UTC ISO8601)	Only contacts whose company activity was first detected at or before this timestamp.
`locations`	array[string]	Company location filter. Examples: `city:San Francisco\|\|California\|\|United States` `state:California\|\|United States` `region:North America` `city:London\|\|\|\|United Kingdom` `country:Brazil`
`functions`	array[string]	Company function filter.
`industries`	array[string]	Company industry filter.
`tlds`	array[string]	Company top-level domain filter.
`technologies`	array[string]	Company technology overlap filter.
`page`	integer	Page number, default 1.
`per_page`	integer	Page size, default 25, max 100.

HTTP request example

POST https://letrics.ai/api/v1/contacts

HTTP request body

{
  "job_titles": ["manager"],
  "departments": ["Finance"],
  "seniorities": ["Manager"],
  "has_personal_email": true,
  "has_linkedin_profile": true,
  "is_decision_maker": true,
  "company_has_generic_email": true,
  "company_has_linkedin_profile": true,
  "added_after": "2026-01-01T00:00:00Z",
  "added_before": "2026-02-01T00:00:00Z",
  "first_seen_after": "2026-01-01T00:00:00Z",
  "first_seen_before": "2026-02-01T00:00:00Z",
  "locations": ["region:North America", "state:California||United States"],
  "functions": ["SaaS"],
  "industries": ["Technology, Information and Media"],
  "exclude_industries": ["Administrative Services"],
  "tlds": ["ai"],
  "technologies": ["Rails"],
  "page": 1,
  "per_page": 25
}

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "first_name": "Ada",
      "last_name": "Lovelace",
      "job_title": "Finance Manager",
      "department": "Finance",
      "seniority": "Manager",
      "email": "[email protected]",
      "linkedin": "https://linkedin.com/in/ada",
      "created_at": "2026-01-05T08:00:00Z",
      "company": {
        "id": 77,
        "name": "Acme AI",
        "domain": "acme.ai",
        "function": "SaaS",
        "industry": "Technology, Information and Media",
        "tld": "ai",
        "technologies": ["Rails"],
        "seen_at": "2026-01-10T10:30:00Z",
        "created_at": "2026-01-03T10:00:00Z"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 1,
    "input": {
      "job_titles": ["manager"],
      "departments": ["Finance"],
      "seniorities": ["Manager"],
      "has_personal_email": true,
      "has_linkedin_profile": true,
      "is_decision_maker": true,
      "company_has_generic_email": true,
      "company_has_linkedin_profile": true,
      "added_after": "2026-01-01T00:00:00Z",
      "added_before": "2026-02-01T00:00:00Z",
      "first_seen_after": "2026-01-01T00:00:00Z",
      "first_seen_before": "2026-02-01T00:00:00Z",
      "locations": ["region:North America", "state:California||United States"],
      "functions": ["SaaS"],
      "industries": ["Technology, Information and Media"],
      "exclude_industries": ["Administrative Services"],
      "tlds": ["ai"],
      "technologies": ["Rails"],
      "page": 1,
      "per_page": 25
    }
  }
}

Companies

Returns companies filtered by company attributes, first-seen timestamp, and added timestamp.