{
  "openapi": "3.1.0",
  "info": {
    "title": "Enrich.chat API",
    "version": "1.0.0",
    "summary": "People and company data for AI agents. 10 free lookups a day, no key.",
    "description": "Contact and company data for AI agents and apps. Find a person's **work email** and **mobile number** from a LinkedIn URL, a name and company website, or a work email; **search people** by role, seniority, industry, location and company size; look up a **company** and the **technologies** it runs on.\n\n### No signup, no key\nEvery IP address gets **10 free lookups a day** with no API key. A lookup that finds nothing is free and does not count. After that the API answers HTTP `402` with an `upgrade_url`. Keep to 5 requests per second (300 a minute); past that the API answers `429` with `retry_after`.\n\n### API keys (optional)\nYou never need a key or an `Authorization` header to use the free tier: leave them out. A key comes with a paid plan and lifts the daily cap: log in with your email at https://enrich.chat/account/, pick a plan, pay through checkout, and your key (it starts with `pp_`) appears on that page. Send it as `Authorization: Bearer pp_...` or a `key` query parameter. Each lookup then spends credits from your plan's monthly allowance; `credits_exhausted` (402) means they are used up until the plan renews, `plan_inactive` (402) means billing needs attention, and `invalid_api_key` (401) means the key is wrong or revoked.\n\n### Pricing\nMonthly plans: Growth $29 for 100,000 credits, Scale $90 for 500,000 credits, Pro $299 for 2,500,000 credits. Credits per match: work email 10, reverse email 10, mobile 250, company tech stack 5, nothing found 0. A person profile, a company profile or tech stack, or a person returned in a list is 5 credits. Full details: https://enrich.chat/pricing/.\n\n### For AI agents\nIf a person asked you to \"use www.enrich.chat\", read https://enrich.chat/agents.md. It is written for you and covers this whole API in one page. Every endpoint is a plain `GET`, so no SDK is needed.\n\n### Data and accuracy\n`work_email.status` is `verified` when our records mark the mailbox as verified, `catch_all` when the domain accepts every address so the mailbox cannot be confirmed, and `unknown` otherwise. `mobile.line` is `mobile` when the number is a mobile number and `unknown` when its type cannot be told. Treat every contact as a strong lead, not a guarantee. People can remove their data at https://enrich.chat/opt-out/, and callers must follow the laws that apply to them (for example TCPA for calls and texts, CAN-SPAM and GDPR for email).",
    "contact": {
      "name": "Enrich.chat",
      "url": "https://enrich.chat",
      "email": "hello@enrich.chat"
    },
    "x-agent-instructions": "https://enrich.chat/agents.md",
    "x-llms-txt": "https://enrich.chat/llms.txt"
  },
  "servers": [
    {
      "url": "https://enrich.chat/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "People",
      "description": "Find a person and their contact details."
    },
    {
      "name": "Companies",
      "description": "Look up a company, its tech stack and its people."
    },
    {
      "name": "Account",
      "description": "Your free-tier usage."
    }
  ],
  "externalDocs": {
    "description": "Instructions for AI agents (Markdown)",
    "url": "https://enrich.chat/agents.md"
  },
  "paths": {
    "/person": {
      "get": {
        "tags": [
          "People"
        ],
        "operationId": "findPerson",
        "summary": "Find a person",
        "description": "Enrich one person. Provide **one** of: `linkedin_url`; `name` with `company` (a website); or `email` (a work email, to find who is behind it). The response carries the work email, the mobile and the profile (name, title, company), limited to `fields`.\n\nTo get a mobile from a name and company, the person must be in our data with a LinkedIn profile; otherwise `mobile` is `null`. `found` is `false` when none of the requested fields came back. People who opted out are never returned.\n\nCredits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.",
        "parameters": [
          {
            "name": "linkedin_url",
            "in": "query",
            "required": false,
            "description": "A LinkedIn profile URL, with or without https://www.",
            "schema": {
              "type": "string"
            },
            "example": "linkedin.com/in/jane-doe-ops"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Full name, first and last. Use with `company`.",
            "schema": {
              "type": "string"
            },
            "example": "Jane Doe"
          },
          {
            "name": "company",
            "in": "query",
            "required": false,
            "description": "A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "A work email address. Personal mailboxes (gmail.com and similar) are not looked up.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "jane.doe@acme.com"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Which fields to return, as a comma list of `email`, `mobile` and `profile` (name, title, company). Default: all three. Ask only for what you need: a mobile costs the most.",
            "schema": {
              "type": "string",
              "pattern": "^(email|mobile|profile)(,(email|mobile|profile))*$",
              "default": "email,mobile,profile"
            },
            "example": "email,mobile"
          }
        ],
        "responses": {
          "200": {
            "description": "The person, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Person"
                    },
                    {
                      "$ref": "#/components/schemas/NotFound"
                    }
                  ]
                },
                "example": {
                  "found": true,
                  "name": "Jane Doe",
                  "title": "VP Operations",
                  "company": {
                    "name": "Acme Logistics"
                  },
                  "linkedin_url": "https://www.linkedin.com/in/jane-doe-ops",
                  "work_email": {
                    "value": "jane.doe@acme.com",
                    "status": "verified"
                  },
                  "mobile": {
                    "value": "+1 415 555 0142",
                    "line": "mobile"
                  },
                  "credits_used": 260,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/person?linkedin_url=linkedin.com/in/jane-doe-ops&fields=email,mobile\""
          }
        ]
      }
    },
    "/email": {
      "get": {
        "tags": [
          "People"
        ],
        "operationId": "findEmail",
        "summary": "Find a work email",
        "description": "Find the work email for a person from `name` and `domain`, or from `linkedin_url`. If we have no address on file, the response is `found: false` with a `guess` built from the company's most common address format. A guess is never data: confirm it before you rely on it, and do not tell the person it was found.\n\nCredits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Full name, first and last.",
            "schema": {
              "type": "string"
            },
            "example": "Jane Doe"
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "linkedin_url",
            "in": "query",
            "required": false,
            "description": "A LinkedIn profile URL, with or without https://www.",
            "schema": {
              "type": "string"
            },
            "example": "linkedin.com/in/jane-doe-ops"
          }
        ],
        "responses": {
          "200": {
            "description": "The email, a guess, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EmailFound"
                    },
                    {
                      "$ref": "#/components/schemas/EmailGuess"
                    },
                    {
                      "$ref": "#/components/schemas/NotFound"
                    }
                  ]
                },
                "example": {
                  "found": true,
                  "work_email": {
                    "value": "jane.doe@acme.com",
                    "status": "verified"
                  },
                  "pattern": "first.last@acme.com",
                  "name": "Jane Doe",
                  "title": "VP Operations",
                  "credits_used": 10,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/email?name=Jane%20Doe&domain=acme.com\""
          }
        ]
      }
    },
    "/mobile": {
      "get": {
        "tags": [
          "People"
        ],
        "operationId": "findMobile",
        "summary": "Find a mobile number",
        "description": "Find the mobile number for a LinkedIn profile. Mobiles cost the most, so ask only when you need one. A landline-only profile returns `found: false`.\n\nCredits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.",
        "parameters": [
          {
            "name": "linkedin_url",
            "in": "query",
            "required": true,
            "description": "A LinkedIn profile URL, with or without https://www.",
            "schema": {
              "type": "string"
            },
            "example": "linkedin.com/in/jane-doe-ops"
          }
        ],
        "responses": {
          "200": {
            "description": "The mobile, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/MobileFound"
                    },
                    {
                      "$ref": "#/components/schemas/NotFound"
                    }
                  ]
                },
                "example": {
                  "found": true,
                  "mobile": {
                    "value": "+1 415 555 0142",
                    "line": "mobile"
                  },
                  "credits_used": 250,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/mobile?linkedin_url=linkedin.com/in/jane-doe-ops\""
          }
        ]
      }
    },
    "/search": {
      "get": {
        "tags": [
          "People"
        ],
        "operationId": "searchPeople",
        "summary": "Search for people",
        "description": "Describe who to find in plain English with `q`, or use the structured filters, or both (a filter replaces what `q` says about the same thing). Results include name, title, company and LinkedIn URL. Call `/person` with a result's `linkedin_url` for verified contact details, or pass `with_email=true` to include the email we hold.\n\nIt works best with a role plus an industry, a location or a company website. A request that is too broad (a role alone) returns `found: false` with a `hint`. Returns up to 25 people per call.\n\nOne search that returns people uses one free lookup, however many people it returns. Credits: 5 per person returned (a 25-person result is 125); 0 when nothing is found.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Who to find, in plain English, up to 300 characters.",
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "example": "VPs of Operations at US logistics companies with 200 to 1,000 employees"
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Job title or function, such as `head of sales` or `recruiter`.",
            "schema": {
              "type": "string"
            },
            "example": "recruiter"
          },
          {
            "name": "seniority",
            "in": "query",
            "required": false,
            "description": "Seniority level.",
            "schema": {
              "type": "string",
              "enum": [
                "c_suite",
                "founder",
                "owner",
                "vp",
                "head",
                "director",
                "manager"
              ]
            },
            "example": "vp"
          },
          {
            "name": "industry",
            "in": "query",
            "required": false,
            "description": "Industry in plain words, such as `hospitals` or `software`.",
            "schema": {
              "type": "string"
            },
            "example": "logistics"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country name, such as `United States`.",
            "schema": {
              "type": "string"
            },
            "example": "United States"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "US state name. Implies the United States.",
            "schema": {
              "type": "string"
            },
            "example": "Texas"
          },
          {
            "name": "employees_min",
            "in": "query",
            "required": false,
            "description": "Minimum company headcount.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000000
            },
            "example": 200
          },
          {
            "name": "employees_max",
            "in": "query",
            "required": false,
            "description": "Maximum company headcount.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000000
            },
            "example": 1000
          },
          {
            "name": "company_domain",
            "in": "query",
            "required": false,
            "description": "Only people at this company website.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many people to return, 1 to 25.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            },
            "example": 10
          },
          {
            "name": "with_email",
            "in": "query",
            "required": false,
            "description": "Only return people we have a work email for, and include it. The email status is `unknown` here because it is not re-checked in this call; use `/person` for the status.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "Matching people, or `found: false` with a `hint`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleResult"
                },
                "example": {
                  "found": true,
                  "count": 2,
                  "people": [
                    {
                      "name": "Dana Whitfield",
                      "title": "Director of IT",
                      "company": "Mercy General",
                      "linkedin_url": "https://www.linkedin.com/in/dana-whitfield"
                    },
                    {
                      "name": "Luis Ortega",
                      "title": "CIO",
                      "company": "St. Anne Health",
                      "linkedin_url": "https://www.linkedin.com/in/luis-ortega"
                    }
                  ],
                  "credits_used": 10,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/search?q=IT%20directors%20at%20US%20hospitals%20with%201000%2B%20employees&limit=5\""
          }
        ]
      }
    },
    "/company": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompany",
        "summary": "Look up a company",
        "description": "Company profile for a website: name, industry, headcount and location. Revenue range and founding year are not returned yet.\n\nCredits: 5 per profile found; 0 when nothing is found.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          }
        ],
        "responses": {
          "200": {
            "description": "The company, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CompanyFound"
                    },
                    {
                      "$ref": "#/components/schemas/NotFound"
                    }
                  ]
                },
                "example": {
                  "found": true,
                  "name": "Acme Logistics",
                  "domain": "acme.com",
                  "industry": "logistics & supply chain",
                  "employees": 420,
                  "state": "Texas",
                  "country": "United States",
                  "credits_used": 5,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/company?domain=acme.com\""
          }
        ]
      }
    },
    "/company/tech": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompanyTech",
        "summary": "Find a company's tech stack",
        "description": "The technologies a company runs on, each with a category (CRM, email, hosting, analytics and so on). Use it to find companies that use a tool or to tailor outreach.\n\nCredits: 5 per company with a tech stack found; 0 when nothing is found.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          }
        ],
        "responses": {
          "200": {
            "description": "The technologies, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TechFound"
                    },
                    {
                      "$ref": "#/components/schemas/NotFound"
                    }
                  ]
                },
                "example": {
                  "found": true,
                  "domain": "acme.com",
                  "company": "Acme Logistics",
                  "technologies": [
                    {
                      "name": "Google Workspace",
                      "category": "Email"
                    },
                    {
                      "name": "HubSpot",
                      "category": "CRM"
                    }
                  ],
                  "credits_used": 5,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/company/tech?domain=acme.com\""
          }
        ]
      }
    },
    "/company/people": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listCompanyPeople",
        "summary": "List people at a company",
        "description": "Find people at a company by its website, optionally narrowed by `title` and `seniority`. Each person has a `linkedin_url`: pass it to `/person` for verified contact details.\n\nOne call that returns people uses one free lookup, however many people it returns. Credits: 5 per person returned; 0 when nothing is found.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Job title or function, such as `head of sales`.",
            "schema": {
              "type": "string"
            },
            "example": "head of sales"
          },
          {
            "name": "seniority",
            "in": "query",
            "required": false,
            "description": "Seniority level.",
            "schema": {
              "type": "string",
              "enum": [
                "c_suite",
                "founder",
                "owner",
                "vp",
                "head",
                "director",
                "manager"
              ]
            },
            "example": "director"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many people to return, 1 to 25.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            },
            "example": 10
          },
          {
            "name": "with_email",
            "in": "query",
            "required": false,
            "description": "Only return people we have a work email for, and include it. The email status is `unknown` here because it is not re-checked in this call; use `/person` for the status.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "People at the company, or `found: false`.",
            "headers": {
              "X-Free-Lookups-Remaining": {
                "$ref": "#/components/headers/FreeRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleResult"
                },
                "example": {
                  "found": true,
                  "count": 2,
                  "domain": "mercy.org",
                  "people": [
                    {
                      "name": "Dana Whitfield",
                      "title": "Director of IT",
                      "company": "Mercy General",
                      "linkedin_url": "https://www.linkedin.com/in/dana-whitfield"
                    },
                    {
                      "name": "Luis Ortega",
                      "title": "CIO",
                      "company": "St. Anne Health",
                      "linkedin_url": "https://www.linkedin.com/in/luis-ortega"
                    }
                  ],
                  "credits_used": 10,
                  "free_lookups_remaining": 24
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/FreeLimit"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/company/people?domain=mercy.org&title=it%20director&limit=5\""
          }
        ]
      }
    },
    "/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsage",
        "summary": "Check your free lookups",
        "description": "How many of today's 10 free lookups this IP address has used. With an API key it returns your plan's credits instead. It does not use a lookup itself, so an agent can check before a large job.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Free lookups used and left today.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Usage"
                    },
                    {
                      "$ref": "#/components/schemas/KeyUsage"
                    }
                  ]
                },
                "example": {
                  "free_lookups_per_day": 10,
                  "used": 1,
                  "remaining": 9,
                  "resets_at": "2026-10-16T09:12:44Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://enrich.chat/v1/usage\""
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pp_...",
        "description": "Optional, and not applied to any endpoint by default: no key or Authorization header is needed for the free tier. An Enrich.chat API key (pp_..., from https://enrich.chat/account/ with a paid plan) lifts the 10-a-day free cap."
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "key",
        "description": "The same key as a query parameter, for tools that cannot set headers."
      }
    },
    "headers": {
      "FreeRemaining": {
        "description": "Free lookups left today for this IP address. Absent when an API key is used.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before trying again.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "schemas": {
      "WorkEmail": {
        "type": "object",
        "required": [
          "value",
          "status"
        ],
        "properties": {
          "value": {
            "type": "string",
            "format": "email",
            "example": "jane.doe@acme.com"
          },
          "status": {
            "type": "string",
            "enum": [
              "verified",
              "catch_all",
              "unknown"
            ],
            "description": "`verified`: our records mark the mailbox as verified. `catch_all`: the domain accepts every address, so the mailbox cannot be confirmed; treat it as risky. `unknown`: not verified."
          }
        }
      },
      "Mobile": {
        "type": "object",
        "required": [
          "value",
          "line"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "International format.",
            "example": "+1 415 555 0142"
          },
          "line": {
            "type": "string",
            "enum": [
              "mobile",
              "unknown"
            ],
            "description": "`mobile` when the number is a mobile number, `unknown` when its type cannot be told. It does not mean the line was called just now."
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Acme Logistics"
          }
        }
      },
      "Billing": {
        "type": "object",
        "properties": {
          "credits_used": {
            "type": "integer",
            "description": "Credits this lookup used: 10 per work email, 250 per mobile, 5 per profile, company, tech stack or person in a list; 0 when nothing was found. On the free tier nothing is charged: this is what a plan would use.",
            "example": 260
          },
          "free_lookups_remaining": {
            "type": "integer",
            "description": "Free lookups left today. Absent when an API key is used.",
            "example": 9
          },
          "credits_left": {
            "type": "integer",
            "description": "Credits left in your plan this period. Present only when an API key is used.",
            "example": 99740
          }
        }
      },
      "NotFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found"
            ],
            "properties": {
              "found": {
                "type": "boolean",
                "const": false
              },
              "hint": {
                "type": "string",
                "description": "What to try next, when there is one."
              }
            }
          }
        ]
      },
      "Person": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found"
            ],
            "description": "Only the fields you asked for are present. A requested field we have no data for is `null`.",
            "properties": {
              "found": {
                "type": "boolean",
                "const": true
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Jane Doe"
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "VP Operations"
              },
              "company": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Company"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "linkedin_url": {
                "type": "string",
                "format": "uri",
                "example": "https://www.linkedin.com/in/jane-doe-ops"
              },
              "work_email": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/WorkEmail"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "mobile": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Mobile"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "EmailFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "work_email"
            ],
            "properties": {
              "found": {
                "type": "boolean",
                "const": true
              },
              "work_email": {
                "$ref": "#/components/schemas/WorkEmail"
              },
              "pattern": {
                "type": "string",
                "description": "The address format this company uses.",
                "example": "first.last@acme.com"
              },
              "name": {
                "type": "string",
                "example": "Jane Doe"
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "VP Operations"
              }
            }
          }
        ]
      },
      "EmailGuess": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "guess"
            ],
            "description": "No address was found. This is the company's most common format applied to the name. It is a guess, never data: do not report it as found.",
            "properties": {
              "found": {
                "type": "boolean",
                "const": false
              },
              "guess": {
                "type": "object",
                "required": [
                  "email",
                  "basis"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "jane.doe@acme.com"
                  },
                  "basis": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      },
      "MobileFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "mobile"
            ],
            "properties": {
              "found": {
                "type": "boolean",
                "const": true
              },
              "mobile": {
                "$ref": "#/components/schemas/Mobile"
              }
            }
          }
        ]
      },
      "PersonSummary": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Dana Whitfield"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "example": "Director of IT"
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "example": "Mercy General"
          },
          "linkedin_url": {
            "type": "string",
            "format": "uri",
            "description": "Pass it to `/person` for verified contact details.",
            "example": "https://www.linkedin.com/in/dana-whitfield"
          },
          "work_email": {
            "$ref": "#/components/schemas/WorkEmail",
            "description": "Only with `with_email=true`. The status is `unknown`: it is not re-checked in this call."
          }
        }
      },
      "PeopleResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "count",
              "people"
            ],
            "properties": {
              "found": {
                "type": "boolean"
              },
              "count": {
                "type": "integer",
                "example": 2
              },
              "domain": {
                "type": "string",
                "description": "Only on `/company/people`.",
                "example": "mercy.org"
              },
              "people": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PersonSummary"
                }
              },
              "hint": {
                "type": "string",
                "description": "Present when nothing matched: how to ask differently."
              }
            }
          }
        ]
      },
      "CompanyFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "domain"
            ],
            "properties": {
              "found": {
                "type": "boolean",
                "const": true
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Acme Logistics"
              },
              "domain": {
                "type": "string",
                "example": "acme.com"
              },
              "industry": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "logistics & supply chain"
              },
              "employees": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 420
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Texas"
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "United States"
              }
            }
          }
        ]
      },
      "TechFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Billing"
          },
          {
            "type": "object",
            "required": [
              "found",
              "domain",
              "technologies"
            ],
            "properties": {
              "found": {
                "type": "boolean",
                "const": true
              },
              "domain": {
                "type": "string",
                "example": "acme.com"
              },
              "company": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Acme Logistics"
              },
              "technologies": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "name"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "HubSpot"
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": "CRM"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "Usage": {
        "type": "object",
        "required": [
          "free_lookups_per_day",
          "used",
          "remaining",
          "resets_at"
        ],
        "properties": {
          "free_lookups_per_day": {
            "type": "integer",
            "example": 10
          },
          "used": {
            "type": "integer",
            "example": 1
          },
          "remaining": {
            "type": "integer",
            "example": 9
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-10-16T09:12:44Z"
          }
        }
      },
      "KeyUsage": {
        "type": "object",
        "required": [
          "plan",
          "credits_granted",
          "credits_used",
          "credits_left"
        ],
        "description": "Returned instead of the free-tier counts when you call /usage with an API key.",
        "properties": {
          "plan": {
            "type": "string",
            "example": "scale"
          },
          "credits_granted": {
            "type": "integer",
            "example": 500000
          },
          "credits_used": {
            "type": "integer",
            "example": 1240
          },
          "credits_left": {
            "type": "integer",
            "example": 498760
          },
          "renews_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "example": "2026-11-16T09:12:44Z"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A stable code to branch on.",
            "example": "bad_request"
          },
          "message": {
            "type": "string",
            "description": "What went wrong and what to do next. Safe to show to a person."
          }
        }
      },
      "FreeLimit": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "type": "object",
            "required": [
              "upgrade_url",
              "resets_at"
            ],
            "properties": {
              "upgrade_url": {
                "type": "string",
                "format": "uri",
                "example": "https://enrich.chat/account/?ref=agent",
                "description": "Show this link to the person so they can log in, pick a plan and get a key."
              },
              "resets_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-16T00:00:00Z"
              },
              "free_lookups_remaining": {
                "type": "integer",
                "const": 0
              }
            }
          }
        ]
      },
      "RateLimit": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "type": "object",
            "required": [
              "retry_after"
            ],
            "properties": {
              "retry_after": {
                "type": "integer",
                "description": "Seconds to wait.",
                "example": 30
              }
            }
          }
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A parameter is missing or invalid. The message says which one and what to send. Do not retry unchanged.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "bad_request",
              "message": "Enter a company website, like acme.com.",
              "docs": "https://enrich.chat/docs"
            }
          }
        }
      },
      "InvalidKey": {
        "description": "The API key is wrong or has been revoked. Check your keys at https://enrich.chat/account/, or leave the key out to use the free tier.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "invalid_api_key",
              "message": "That API key was not accepted. API keys are not being issued yet, so leave the key out to use the free tier, or email hello@enrich.chat for access.",
              "upgrade_url": "https://enrich.chat/account/?ref=agent"
            }
          }
        }
      },
      "FreeLimit": {
        "description": "Today's free lookups are used up. Stop calling the API, tell the person, and show them `upgrade_url`. Resume after `resets_at`, or once they have a key from https://enrich.chat/account/.",
        "headers": {
          "X-Free-Lookups-Remaining": {
            "$ref": "#/components/headers/FreeRemaining"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/FreeLimit"
            },
            "example": {
              "error": "free_limit_reached",
              "message": "You've used today's 10 free lookups.",
              "upgrade_url": "https://enrich.chat/account/?ref=agent",
              "resets_at": "2026-10-16T00:00:00Z",
              "free_lookups_remaining": 0
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too many requests. Wait `retry_after` seconds, then continue.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimit"
            },
            "example": {
              "error": "too_many_requests",
              "message": "Too many requests. Wait 30 seconds, then continue.",
              "retry_after": 30
            }
          }
        }
      },
      "Unavailable": {
        "description": "The data service is slow or unreachable. Retry once after `retry_after` seconds. Nothing was billed and no free lookup was used.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimit"
            },
            "example": {
              "error": "temporarily_unavailable",
              "message": "The data service is slow or unreachable. Retry once in a few seconds. You were not charged and no free lookup was used.",
              "retry_after": 5
            }
          }
        }
      }
    }
  }
}