{"openapi":"3.1.0","info":{"title":"Tamozo Data API","description":"\nSearch Tamozo's people and company data, or pull everything we hold on someone\nyou already know.\n\n| | |\n|---|---|\n| `POST /v1/people/search` | Find people by title, seniority, location, industry, employer, skills, tenure — or, with `product_hunt_only: true`, Product Hunt profiles (worldwide). **Free, and returns no contact details** |\n| `POST /v1/companies/search` | Find companies by industry, size, location, founding year |\n| `POST /v1/companies/enrich` | Everything we hold on one company — by website, LinkedIn page or id |\n| `POST /v1/people/enrich` | Everything we hold on one person, **with their contacts** — by a search `id`, LinkedIn, Product Hunt, X, Instagram or their website. `contact_types` picks which contacts |\n\n### Authentication\n\nSend your key on every request:\n\n```\nAuthorization: Bearer <your key>\n```\n\n### What it costs\n\n**Search is free and returns no identifiers** — no LinkedIn, X or other social\nlink, no email, no phone. Every contact comes from enrichment: **1 credit for the\nrecord, plus 1 per contact type delivered** (LinkedIn, X, Product Hunt, GitHub,\nInstagram, a personal site, email, phone), **13 at most**. Narrow it with `contact_types` to pay for fewer. A\nchannel you looked the person up by is never charged for, and **nothing is\ncharged unless we find the record** — a 404 or a rejected request is free. Every\nenrichment response itemises its own charge under `credits`, and\n`X-Credits-Balance` is what you have left.\n\nSearch is bounded by volume instead of price: **5,000 records a UTC day**, in\nrecords rather than requests, reported in `X-Search-Records-Remaining`. Reaching\nit never stops you enriching, and an empty balance never stops you searching.\n\n### Conventions\n\nParameters are AND-ed; values within one list are OR-ed. Every parameter is\noptional, and an unknown one is rejected by name rather than ignored. Results\nare paged with `page`; the page size is ours (100 today, reported in\n`pagination.per_page`, not a request parameter), up to 50,000 records per\nsearch; `breadcrumbs` in each response shows how the server read your request,\nand `notes` carries warnings about that specific query.\n\n### Coverage, before you build on it\n\n* **People SEARCH is United States only** — everything else is under 0.1% of\n  records. `/v1/people/enrich` is not limited that way: hand it a LinkedIn URL\n  for someone outside that coverage and the profile is read for you.\n* **Social media accounts** — X, GitHub, Instagram, a personal site — are held\n  for some people, and LinkedIn for almost everyone. `/v1/people/enrich` delivers\n  them, and you can also look a person up by any of them, or by a work email.\n* **A `null` means we do not have that information.** It never means zero. If a\n  company shows `num_employees: null`, we do not know its headcount — the\n  company is not empty. Most companies have either funding figures or a\n  headcount on file, rarely both.\n\nRecords are a snapshot: a person's role and employer can lag reality by months.\n","version":"1"},"servers":[{"url":"https://api.tamozo.com","description":"Production"}],"paths":{"/v1/people/search":{"post":{"tags":["people"],"summary":"Search people","description":"Search people.\n\nEvery parameter is optional and they are AND-ed; values within a list are\nOR-ed. Pages are stable and tile exactly. A page whose filter set is too\nbroad to serve at that depth is refused (422 `too_broad`) rather than run —\nthe data is there, the query as phrased cannot be paged that far.","operationId":"search_v1_people_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleSearchParams"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/people/enrich":{"post":{"tags":["people"],"summary":"Everything we hold on one person","description":"Everything we hold on one person, found by any channel that identifies\nthem: LinkedIn, Product Hunt, X, Instagram or their personal website.\n\nThe sources are consulted in the order that can actually answer. A LinkedIn\nURL reaches the people data directly. Every other channel is resolved\nthrough Product Hunt first, and if that account links a LinkedIn we hold,\nthe full profile is returned with it — otherwise you get what Product Hunt\nknows, in the same shape, rather than a 404 for someone we can see.","operationId":"enrich_v1_people_enrich_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichParams"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/companies/search":{"post":{"tags":["companies"],"summary":"Search companies","description":"Search companies. `total_entries` here is an exact count, not an estimate.","operationId":"search_v1_companies_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchParams"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/companies/enrich":{"post":{"tags":["companies"],"summary":"Everything we hold on one company","description":"Everything we hold on one company, found by website, LinkedIn page,\nLinkedIn id or name.\n\nIdentifiers are tried most-precise first — an id, then a LinkedIn page, then\na domain, then a name — and the first that matches wins, so passing several\nis a fallback chain rather than a conflict.","operationId":"enrich_v1_companies_enrich_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyEnrichParams"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CompanyEnrichParams":{"properties":{"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url","description":"Company website or bare domain; matched on the host."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"A LinkedIn company page URL."},"linkedin_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Linkedin Id","description":"LinkedIn's numeric company id — the same id people rows carry."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Any address at the company; matched on its domain."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Exact company name. Names are not unique, so a name match reports the alternatives it found rather than guessing between them."}},"additionalProperties":false,"type":"object","title":"CompanyEnrichParams","description":"POST /v1/companies/enrich -- one company, by whatever identifies it.\n\nCoverage decided which identifiers are offered, measured over the 202,628\ndistinct companies (2026-09-23): **website 86%**, a LinkedIn company URL\n47%, a numeric LinkedIn id 14%, name 100% but NOT unique. So the domain is\nthe strongest key here — the reverse of people, where LinkedIn is — which\nsuits the caller, because a domain is what a CRM holds.","examples":[{"website_url":"stripe.com"},{"linkedin_url":"https://www.linkedin.com/company/stripe/"},{"linkedin_id":2135371},{"email":"hi@internetisbeautiful.com"}]},"CompanySearchParams":{"properties":{"page":{"type":"integer","minimum":1.0,"title":"Page","description":"1-based. The page size is set by the service.","default":1},"organization_industries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Organization Industries","description":"Industry labels from the fixed taxonomy, any case; an unknown label is refused. Labels: Accounting, Advertising, Aerospace, Agriculture, Airlines, Apparel, Architecture, Artificial Intelligence, Arts, Automotive, Aviation, Banking, Beverages, Biotechnology, Broadcasting, Building Materials, Chemicals, Civic Organizations, Civil Engineering, Cleaning Services, Cloud Computing, Computer Hardware, Construction, Consumer Electronics, Consumer Goods, Consumer Services, Cybersecurity, Data Analytics, Defense, Design, Distribution, E-commerce, EdTech, Education, Electronics Manufacturing, Energy, Entertainment, Environmental Services, Facilities Services, Farming, Fashion Retail, Film, Financial Services, Fintech, Fishing, Fitness, Food Production, Forestry, Freight Delivery, Furniture, Gaming, Government, Grocery, Healthcare, Higher Education, Hospitality, Hospitals, Hotels, Human Resources, Industrial Machinery, Information Technology, Insurance, Internet Services, Investment Management, IT Services, Jewelry, Law Enforcement, Legal Services, Leisure, Libraries, Life Sciences, Logistics, Luxury Goods, Management Consulting, Manufacturing, Maritime Shipping, Marketing, Media, Medical Clinics, Medical Devices, Mental Health, Metals, Military, Mining, Museums, Music, Networking Equipment, Nonprofit, Oil and Gas, Outsourcing, Packaging, Personal Services, Pharmaceuticals, Philanthropy, Photography, Plastics, Private Equity, Professional Services, Professional Training, Property Management, Public Policy, Public Relations, Publishing, Rail Transport, Real Estate, Recreation, Recruiting, Recycling, Religious Institutions, Renewable Energy, Research, Restaurants, Retail, Security Services, Semiconductors, Shipbuilding, Software, Sports, Staffing, Supply Chain, Telecom, Textiles, Tobacco, Tourism, Travel, Trucking, Urban Planning, Utilities, Venture Capital, Veterinary, Video Production, Warehousing, Waste Management, Water Utilities, Wellness, Wholesale, Other."},"organization_keyword_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Organization Keyword Tags","description":"Free-text industry keywords, matched as substrings against the source's own industry string."},"organization_locations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Organization Locations","description":"Headquarters country or region, matched as a substring."},"organization_num_employees_range":{"anyOf":[{"$ref":"#/components/schemas/RangeParam"},{"type":"null"}]},"organization_founded_year_range":{"anyOf":[{"$ref":"#/components/schemas/RangeParam"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"CompanySearchParams","description":"POST /v1/companies/search.","examples":[{"organization_industries":["Fintech"],"organization_num_employees_range":{"max":500,"min":50}}]},"EnrichParams":{"properties":{"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"e.g. https://www.linkedin.com/in/jane-doe/"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The `id` a search returned (an opaque `tmz_…` token). A LinkedIn slug is accepted here too."},"producthunt_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Producthunt Url","description":"A Product Hunt profile URL or handle, e.g. @jane."},"x_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X Url","description":"An X (Twitter) profile URL or handle."},"instagram_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instagram Url","description":"An Instagram profile URL or handle."},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url","description":"A personal website; matched on its host, so any page of it works."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"A work email address. Matched against the address published on a person's own public maker profile — which is the COMPANY's address, so it identifies them only as far as the company is theirs. A shared inbox is reported rather than guessed at."},"contact_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Contact Types","description":"Which contacts to return, e.g. `[\"x\"]` or `[\"linkedin\", \"email\"]`. Omit for every contact we hold. Each contact TYPE delivered costs 1 credit on top of the 1-credit base (several emails are one credit); 13 credits at most."},"github_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Url","description":"A GitHub profile URL or username. **Accepted but not yet searchable** — it returns 501 `not_searchable_yet` when it is the only identifier you pass, so that your integration does not have to change when the data lands. GitHub is already RETURNED, under `contact.github_url`, for people we hold it for."}},"additionalProperties":false,"type":"object","title":"EnrichParams","description":"Pass **any one** of these — whichever identifier you happen to hold.\n\nA LinkedIn URL reaches the main people data directly. The other channels are\nresolved through public maker profiles first, and bridge to the full record\nwhen that profile links a LinkedIn we hold.\n\n`email` and `github_url` are deliberately absent: nothing on our side could\nmatch an email address, and GitHub is only ever known after we have found\nsomeone. A parameter that can only answer \"not found\" would read as \"you\nhave no such person\".","examples":[{"linkedin_url":"https://www.linkedin.com/in/brentorred/"},{"x_url":"https://x.com/naval"},{"producthunt_url":"@rishabh_dodo"},{"email":"hi@internetisbeautiful.com"}]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PeopleSearchParams":{"properties":{"page":{"type":"integer","minimum":1.0,"title":"Page","description":"1-based. The page size is set by the service.","default":1},"person_titles":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Titles","description":"Job titles, matched as substrings. Which title they are matched against is `person_title_scope`: by default the current OR the previous one."},"person_title_scope":{"type":"string","enum":["current","previous","any"],"title":"Person Title Scope","description":"Which title `person_titles` is matched against: \"current\" (the job they hold now), \"previous\" (the job just before it) or \"any\" (either -- the default, which also finds people who have since moved on).","default":"any"},"person_past_titles":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Past Titles","description":"Titles matched against previous roles only."},"person_seniorities":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Seniorities","description":"One or more of ['Junior', 'Mid', 'Senior']."},"person_locations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Locations","description":"Countries, US states or cities, in one list — each term is routed to the field it can match."},"person_industries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Industries","description":"Industry labels from the fixed taxonomy, any case; an unknown label is refused. This is the industry on the person's profile, which usually but not always matches their employer's. Labels: Accounting, Advertising, Aerospace, Agriculture, Airlines, Apparel, Architecture, Artificial Intelligence, Arts, Automotive, Aviation, Banking, Beverages, Biotechnology, Broadcasting, Building Materials, Chemicals, Civic Organizations, Civil Engineering, Cleaning Services, Cloud Computing, Computer Hardware, Construction, Consumer Electronics, Consumer Goods, Consumer Services, Cybersecurity, Data Analytics, Defense, Design, Distribution, E-commerce, EdTech, Education, Electronics Manufacturing, Energy, Entertainment, Environmental Services, Facilities Services, Farming, Fashion Retail, Film, Financial Services, Fintech, Fishing, Fitness, Food Production, Forestry, Freight Delivery, Furniture, Gaming, Government, Grocery, Healthcare, Higher Education, Hospitality, Hospitals, Hotels, Human Resources, Industrial Machinery, Information Technology, Insurance, Internet Services, Investment Management, IT Services, Jewelry, Law Enforcement, Legal Services, Leisure, Libraries, Life Sciences, Logistics, Luxury Goods, Management Consulting, Manufacturing, Maritime Shipping, Marketing, Media, Medical Clinics, Medical Devices, Mental Health, Metals, Military, Mining, Museums, Music, Networking Equipment, Nonprofit, Oil and Gas, Outsourcing, Packaging, Personal Services, Pharmaceuticals, Philanthropy, Photography, Plastics, Private Equity, Professional Services, Professional Training, Property Management, Public Policy, Public Relations, Publishing, Rail Transport, Real Estate, Recreation, Recruiting, Recycling, Religious Institutions, Renewable Energy, Research, Restaurants, Retail, Security Services, Semiconductors, Shipbuilding, Software, Sports, Staffing, Supply Chain, Telecom, Textiles, Tobacco, Tourism, Travel, Trucking, Urban Planning, Utilities, Venture Capital, Veterinary, Video Production, Warehousing, Waste Management, Water Utilities, Wellness, Wholesale, Other."},"person_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Skills","description":"Self-reported skills; any overlap."},"person_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Person Languages","description":"Languages; any overlap."},"organization_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Organization Names","description":"Employer names. Exact and case-sensitive. Which employer they are matched against is `organization_scope`: by default the current one."},"organization_scope":{"type":"string","enum":["current","previous","any"],"title":"Organization Scope","description":"Which employer `organization_names` is matched against: \"current\" (the default), \"previous\" (the employer just before the current one) or \"any\" (either). \"previous\" and \"any\" need another filter beside them, such as a title or a location.","default":"current"},"organization_linkedin_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Organization Linkedin Ids","description":"LinkedIn numeric company ids of the current employer."},"organization_industries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Organization Industries","description":"The CURRENT EMPLOYER's industry, from the same fixed labels as `person_industries`, any case. Use it to keep a sector search to people who actually work at companies in that sector. Only people whose employer we can identify (about 60%) can match, so it narrows harder than `person_industries`."},"person_years_experience_range":{"anyOf":[{"$ref":"#/components/schemas/RangeParam"},{"type":"null"}],"description":"Total career length. Coarse: see `notes` in the response."},"person_months_in_role_range":{"anyOf":[{"$ref":"#/components/schemas/RangeParam"},{"type":"null"}],"description":"Months in the current role. {\"max\": 12} = joined within a year."},"person_open_to_offers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Person Open To Offers"},"person_has_management_experience":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Person Has Management Experience"},"product_hunt_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Product Hunt Only","description":"true = search Product Hunt profiles instead of the people data: makers and members worldwide, not only the US. Supports `person_titles`, `person_seniorities` (Product Hunt levels: ['founder', 'c_level', 'vp', 'head', 'director', 'manager', 'senior']), `organization_names`, `has_x` and the four label filters (`product_topics`, `company_topics`, `product_categories`, `company_categories`); any other filter is refused rather than silently ignored."},"has_x":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has X","description":"Only people who list their OWN X account (true) or who list none (false). Requires `product_hunt_only: true` — X accounts come from Product Hunt profiles."},"product_topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Product Topics","description":"Product Hunt topics of the products the person launched themselves, e.g. \"Artificial Intelligence\", \"SaaS\", \"Developer Tools\". Exact label, any case. Requires `product_hunt_only: true`."},"company_topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Company Topics","description":"Product Hunt topics of the person's company. Exact label, any case. Requires `product_hunt_only: true`."},"product_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Product Categories","description":"Product Hunt categories of the products the person launched themselves -- the finer vocabulary, e.g. \"AI Voice Agents\", \"AI Sales Tools\". Exact label, any case. Requires `product_hunt_only: true`."},"company_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Company Categories","description":"Product Hunt categories of the person's company. Exact label, any case. Requires `product_hunt_only: true`."}},"additionalProperties":false,"type":"object","title":"PeopleSearchParams","description":"POST /v1/people/search.","examples":[{"page":1,"person_industries":["Software"],"person_locations":["Texas","Austin"],"person_seniorities":["Senior"],"person_titles":["VP of Sales","Head of Sales"]},{"organization_linkedin_ids":[2135371],"person_months_in_role_range":{"max":12}},{"has_x":true,"person_seniorities":["founder"],"product_hunt_only":true}]},"RangeParam":{"properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min"},"max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max"}},"additionalProperties":false,"type":"object","title":"RangeParam","description":"`{\"min\": 1, \"max\": 50}` -- Apollo's `revenue_range[min]` shape."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Your API key. Sent as `Authorization: Bearer <key>` on every request."}}},"tags":[{"name":"people","description":"Search for people, or enrich one you already know."},{"name":"companies","description":"Search company firmographics."}],"security":[{"ApiKey":[]}]}