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.

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_emails`	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.
`added_after`	string (UTC ISO8601)	Only contacts whose company was created at or after this timestamp.
`added_before`	string (UTC ISO8601)	Only contacts whose company was created at or before this timestamp.
`locations`	array[string]	Company location filter. Examples: `city:San Francisco\|\|California\|\|United States` `state:California\|\|United States` `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_emails": true,
  "has_linkedin_profile": true,
  "is_decision_maker": true,
  "added_after": "2026-01-01T00:00:00Z",
  "added_before": "2026-02-01T00:00:00Z",
  "locations": ["state:California||United States"],
  "functions": ["SaaS"],
  "industries": ["Technology, Information and Media"],
  "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"],
        "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_emails": true,
      "has_linkedin_profile": true,
      "is_decision_maker": true,
      "added_after": "2026-01-01T00:00:00Z",
      "added_before": "2026-02-01T00:00:00Z",
      "locations": ["state:California||United States"],
      "functions": ["SaaS"],
      "industries": ["Technology, Information and Media"],
      "tlds": ["ai"],
      "technologies": ["Rails"],
      "page": 1,
      "per_page": 25
    }
  }
}

Companies

Returns companies filtered by company attributes and creation timestamp.