> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up a company

> Get public company details, such as name, logo, country and technologies, from a domain or work email.

### Good to know

* **Send `domain` or `email`, not both.** With an email, only the domain is used. Send a bare hostname such as `stripe.com`. A URL like `https://stripe.com/about` returns `invalid_input`.
* **Check `free_email_domain` first.** Addresses at Gmail, Outlook and similar providers belong to people, not companies, so `name`, `description` and `logo_url` are `null`.
* **Missing fields are normal.** Small sites often have no description, no social links or no reachable homepage. Every field can be `null` or empty, so render what is there.
* **Results are cached per domain for up to 30 days.** A company that changes its website may take that long to show the change. Every lookup costs 1 credit, cached or not.
* **No firmographics.** The result is built from the company's own homepage and DNS records. It has no employee count, revenue or industry.
* **`technologies` is evidence, not a full inventory.** A service shows up only when it leaves a trace in DNS or on the homepage.
* **`company_unavailable` is free.** If the lookup can't complete, the request returns `503` and is not charged. Try again after a short delay.

<Card title="API reference introduction" icon="book-open" href="/api-reference/introduction">
  Base URL, authentication and conventions shared by every endpoint.
</Card>


## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/company/lookup
openapi: 3.1.0
info:
  title: Finowl API
  version: '1.0'
  description: >
    Check emails and passwords against known data breaches, predict gender from
    names

    and emails, check cold-email compliance, validate email addresses and phone
    numbers,

    look up companies by domain and geolocate IP addresses. Every endpoint is a
    JSON

    `POST` authenticated with a bearer API key.
servers:
  - url: https://api.finowl.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Breaches
    description: Check whether an email or password appears in known data breaches.
  - name: Gender
    description: Predict gender from a name or email, one at a time or in batches.
  - name: Compliance
    description: >-
      Place an email address in a jurisdiction and return that jurisdiction's
      cold-email rule.
  - name: Email validation
    description: >-
      Check whether an email address can receive mail, and catch typos,
      disposable and role addresses.
  - name: Company
    description: Look up public company details from a domain or work email.
  - name: IP
    description: Geolocate an IP address and flag hosting, proxy and Tor traffic.
  - name: Phone
    description: Validate, format and classify a phone number.
paths:
  /v1/company/lookup:
    post:
      tags:
        - Company
      summary: Look up a company
      description: >
        Returns public company details for a domain, or for the domain of a work
        email: name,

        description, country, language, logo, social profiles, email provider
        and detected

        technologies. Finowl reads the company's public homepage and its DNS
        records on its own

        infrastructure. No paid enrichment service is called.


        Send exactly one of `domain` or `email`. Domains are lowercased, and a
        trailing dot and a

        leading `www.` are removed, so `WWW.Stripe.com.` and `stripe.com` return
        the same result.

        Free mailbox domains such as `gmail.com` return `free_email_domain:
        true` without reading

        a homepage.


        Results are cached per domain for up to 30 days.


        Costs **1 credit**. A `503` where the lookup could not complete is not
        charged.
      operationId: lookupCompany
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  title: By domain
                  additionalProperties: false
                  required:
                    - domain
                  properties:
                    domain:
                      type: string
                      maxLength: 253
                      description: >-
                        A bare hostname such as `stripe.com`. URLs with a
                        scheme, path or port, such as
                        `https://stripe.com/about`, return `invalid_input`.
                      example: stripe.com
                - type: object
                  title: By email
                  additionalProperties: false
                  required:
                    - email
                  properties:
                    email:
                      type: string
                      format: email
                      maxLength: 254
                      description: >-
                        A work email. Only its domain is used. It must be a
                        plain address with a dotted domain. Display names,
                        quoted local parts and IP-address domains return
                        `invalid_input`.
                      example: jane@stripe.com
            examples:
              domain:
                summary: By domain
                value:
                  domain: stripe.com
              email:
                summary: By email
                value:
                  email: jane@stripe.com
              free:
                summary: Free mailbox domain
                value:
                  email: jane.doe@gmail.com
      responses:
        '200':
          description: >-
            The lookup completed. Fields that could not be found are `null` or
            empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResult'
              examples:
                company:
                  summary: Company domain
                  value:
                    domain: stripe.com
                    name: Stripe
                    description: >-
                      Stripe powers online payment processing for internet
                      businesses.
                    country_code: US
                    country: United States
                    language: en
                    logo_url: https://stripe.com/img/v3/home/social.png
                    website_reachable: true
                    social:
                      linkedin: https://www.linkedin.com/company/stripe
                      twitter: https://twitter.com/stripe
                    email_provider: google_workspace
                    technologies:
                      - google_workspace
                      - hubspot
                      - salesforce
                    free_email_domain: false
                free:
                  summary: Free mailbox domain
                  value:
                    domain: gmail.com
                    name: null
                    description: null
                    country_code: ''
                    country: ''
                    language: null
                    logo_url: null
                    website_reachable: false
                    social: {}
                    email_provider: google_workspace
                    technologies: []
                    free_email_domain: true
                unreachable:
                  summary: Website not reachable
                  value:
                    domain: example-holdings.de
                    name: null
                    description: null
                    country_code: DE
                    country: Germany
                    language: null
                    logo_url: null
                    website_reachable: false
                    social: {}
                    email_provider: microsoft_365
                    technologies:
                      - microsoft_365
                    free_email_domain: false
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: >-
            `company_unavailable`: the lookup could not complete, for example
            because DNS did not answer. Not charged. Retry after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: company_unavailable
        '504':
          $ref: '#/components/responses/Unconfirmed'
components:
  schemas:
    CompanyResult:
      type: object
      required:
        - domain
        - name
        - description
        - country_code
        - country
        - language
        - logo_url
        - website_reachable
        - social
        - email_provider
        - technologies
        - free_email_domain
      properties:
        domain:
          type: string
          description: >-
            The normalized domain that was looked up: lowercase, with no `www.`
            prefix or trailing dot.
        name:
          type:
            - string
            - 'null'
          description: >-
            The company name from the homepage. `null` when unknown or for free
            mailbox domains.
        description:
          type:
            - string
            - 'null'
          description: The homepage's own description of the company. `null` when unknown.
        country_code:
          type: string
          description: >-
            ISO 3166-1 alpha-2 code of the company's likely country, from the
            domain, the homepage and its phone links. Empty when unknown.
        country:
          type: string
          description: The country name for `country_code`. Empty when unknown.
        language:
          type:
            - string
            - 'null'
          description: >-
            The homepage's declared language, such as `en` or `de`. `null` when
            unknown.
        logo_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            An absolute `https` URL of the best available logo or icon: the
            Apple touch icon, then the social sharing image, then the largest
            icon, then `/favicon.ico`. `null` when none was found. The image is
            hosted by the company, so cache it yourself if you show it often.
        website_reachable:
          type: boolean
          description: >-
            `true` when the homepage answered over HTTPS. When `false`, homepage
            fields are `null` and the result comes from DNS only.
        social:
          type: object
          description: >-
            Company profiles linked from the homepage, as absolute URLs. Only
            profiles that were found are present, so the object can be empty.
          additionalProperties: false
          properties:
            linkedin:
              type: string
              format: uri
              description: The LinkedIn company page.
            twitter:
              type: string
              format: uri
              description: The X or Twitter profile.
            facebook:
              type: string
              format: uri
              description: The Facebook page.
            instagram:
              type: string
              format: uri
              description: The Instagram profile.
            youtube:
              type: string
              format: uri
              description: The YouTube channel.
            github:
              type: string
              format: uri
              description: The GitHub organization.
            tiktok:
              type: string
              format: uri
              description: The TikTok profile.
        email_provider:
          type:
            - string
            - 'null'
          enum:
            - google_workspace
            - microsoft_365
            - zoho
            - proton
            - fastmail
            - yandex
            - other
            - null
          description: >-
            Who hosts the domain's email, from its MX records. `null` when the
            domain has no mail servers. Treat values you don't recognize like
            `other`. For free mailbox domains this names the provider's own mail
            system, so `gmail.com` returns `google_workspace` and `outlook.com`
            returns `microsoft_365`.
        technologies:
          type: array
          items:
            type: string
          description: >
            Services detected from the domain's DNS verification and SPF records
            and from the homepage, sorted and unique.

            Examples: `google_workspace`, `microsoft_365`, `hubspot`,
            `salesforce`, `mailchimp`, `sendgrid`, `amazon_ses`,

            `mailgun`, `postmark`, `zendesk`, `freshdesk`, `intercom`,
            `atlassian`, `docusign`, `stripe`, `shopify`,

            `wordpress`, `wix`, `squarespace`, `webflow`, `cloudflare`,
            `google_analytics`, `google_tag_manager`,

            `facebook_pixel`, `hotjar`, `segment`, `apple`, `adobe`, `slack`,
            `zoom`, `openai`, `vercel`, `nextjs`, `onetrust`,

            `mimecast`, `proofpoint`. The list is not exhaustive and new values
            may be added. A verification record only

            shows the domain was verified with a service at some point, not that
            it is still in use.
        free_email_domain:
          type: boolean
          description: >-
            `true` for free mailbox domains such as `gmail.com`. The address
            belongs to a person, not a company, so the homepage is not read and
            `name`, `description` and `logo_url` are `null`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              description: >-
                A stable, machine-readable error code. See the Errors page for
                the full list.
              example: invalid_input
  responses:
    InvalidInput:
      description: The request body is not valid. Fix the request before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_input
    Unauthorized:
      description: The API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
    TooManyRequests:
      description: >
        `rate_limited` (too many requests this minute), `quota_exceeded` (not
        enough credits) or

        `provider_rate_limited` (Finowl intelligence is busy). Check the
        `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
    Unconfirmed:
      description: >-
        The lookup did not finish in time. It may or may not have run, and the
        request was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_response_unconfirmed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
        dashboard under **API Keys**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.