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

# Reveal Company

> Identify the companies behind a website visitor's IP address, with the visitor's approximate location.

Send one public IPv4 or IPv6 address and get back the companies behind it and
its approximate location. For pricing and best practices, see the
[Website Visitor Reveal guide](/guides/website-visitor-reveal).

<Note>
  Website Visitor Reveal must be enabled for your account. Existing customers can
  request access at [support@tamradar.com](mailto:support@tamradar.com).
</Note>

```bash theme={null}
curl -X POST "https://api.tamradar.com/v1/company-reveal" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "17.253.144.10"}'
```

## Match or no match

Every lookup returns a final answer within 25 seconds. Both outcomes return `200`. Check `data.companies`:

```javascript theme={null}
if (response.data.companies.length > 0) {
  // Match: one lookup charge, shown in usage.total_usd
} else {
  // No match: free
}
```

* A company's `country` is its headquarters country; the visitor's approximate location is in `data.ip_geo`, which can be `null`.
* `domain` is always present; other company fields are `null` when unknown.

## Request rules

* Send only `ip` in the JSON body. Private and reserved addresses, ports, URLs and CIDR ranges return `400`.
* Use exactly `POST https://api.tamradar.com/v1/company-reveal`, with no query parameters or trailing slash.


## OpenAPI

````yaml api_specs.yaml POST /v1/company-reveal
openapi: 3.0.0
info:
  title: TAMradar API
  version: '1.0'
  description: Canonical OpenAPI spec for TAMradar customer-facing APIs.
servers:
  - url: https://api.tamradar.com
    description: Production API server
security: []
paths:
  /v1/company-reveal:
    post:
      tags:
        - Website Visitor Reveal
      summary: Reveal the company behind an IP address
      description: >-
        Resolves one public IPv4 or IPv6 address to the companies behind it and
        the address's approximate location.


        A lookup that returns at least one company is charged once, however many
        companies it returns. A lookup with no match is free. Every request is
        an independent lookup: repeating the same IP is charged again, so store
        results on your side.


        Requests count toward your account's write rate limit, shared with radar
        creation. Website Visitor Reveal must be enabled for your API key.
      operationId: revealCompany
      requestBody:
        required: true
        description: JSON object containing only `ip`. Maximum 2048 bytes.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyRevealRequest'
            example:
              ip: 17.253.144.10
      responses:
        '200':
          description: >-
            Lookup completed. An empty `companies` array means no company was
            found; that lookup is free.
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Identifier for this lookup. Equals `request_id` in the body.
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Your account's per-minute write budget
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Tokens remaining right now
            X-RateLimit-Reset:
              schema:
                type: integer
              description: >-
                Seconds until the budget is fully refilled (not a Unix
                timestamp)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealResponse'
              examples:
                match:
                  summary: Company found (charged)
                  value:
                    status: success
                    code: 200
                    timestamp: '2026-10-13T09:00:00Z'
                    request_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    data:
                      ip: 17.253.144.10
                      ip_geo:
                        city: Cupertino
                        state: California
                        country: United States
                      companies:
                        - domain: apple.com
                          name: Apple Inc
                          profile_url: https://www.linkedin.com/company/apple
                          industry: Consumer Product Manufacturing
                          employees_count: 166000
                          country: United States
                    usage:
                      total_usd: 0.05
                      balance_remaining_usd: 124.95
                no_match:
                  summary: No company found (free)
                  value:
                    status: success
                    code: 200
                    timestamp: '2026-10-13T09:00:00Z'
                    request_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
                    data:
                      ip: 81.2.69.160
                      ip_geo:
                        city: London
                        state: England
                        country: United Kingdom
                      companies: []
                    usage:
                      total_usd: 0
                      balance_remaining_usd: 124.95
        '400':
          description: >-
            Invalid request — not charged. The body is not one public IPv4 or
            IPv6 address, or the JSON is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              examples:
                invalid_ip:
                  summary: Not a public IP address
                  value:
                    status: error
                    code: 400
                    message: Invalid request.
                    errors:
                      - field: ip
                        reason: >-
                          Expected one public IPv4 or IPv6 address in a JSON
                          object.
                    timestamp: '2026-10-13T09:00:00Z'
                    error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
                malformed_json:
                  summary: Malformed JSON
                  value:
                    status: error
                    code: 400
                    message: Malformed JSON body.
                    errors: []
                    timestamp: '2026-10-13T09:00:00Z'
                    error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '401':
          description: Missing, invalid or inactive API key — not charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 401
                message: Invalid or inactive API key
                errors:
                  - field: x-api-key
                    reason: Invalid or inactive API key
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '402':
          description: Not enough balance for this lookup — not charged. Top up and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 402
                message: Insufficient balance for this lookup.
                errors:
                  - field: balance
                    reason: Insufficient eligible balance.
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '403':
          description: >-
            Website Visitor Reveal is not enabled for this API key or account —
            not charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 403
                message: Website Visitor Reveal is not enabled for this key or account.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '413':
          description: Request body larger than 2048 bytes — not charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 413
                message: The body must not exceed 2048 bytes.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '415':
          description: '`Content-Type` is not `application/json` — not charged.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 415
                message: Use application/json.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '429':
          description: >-
            Rate limit exceeded — no lookup was performed and nothing was
            charged. Check `Retry-After` to know when to retry.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until your budget is restored
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Your account's per-minute write budget
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Tokens remaining right now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 429
                message: Rate limit exceeded.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '500':
          description: The lookup could not be completed — not charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 500
                message: An internal server error occurred.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
        '503':
          description: >-
            Service temporarily unavailable — no lookup was performed and
            nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRevealError'
              example:
                status: error
                code: 503
                message: An internal server error occurred.
                errors: []
                timestamp: '2026-10-13T09:00:00Z'
                error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CompanyRevealRequest:
      type: object
      required:
        - ip
      properties:
        ip:
          type: string
          maxLength: 45
          description: >-
            One public IPv4 or IPv6 address. Private, reserved, loopback,
            link-local and multicast addresses are rejected, as are ports, URLs,
            CIDR ranges and zone IDs.
          example: 17.253.144.10
      additionalProperties: false
    CompanyRevealResponse:
      type: object
      required:
        - status
        - code
        - timestamp
        - request_id
        - data
        - usage
      properties:
        status:
          type: string
          enum:
            - success
        code:
          type: integer
          enum:
            - 200
        timestamp:
          type: string
          format: date-time
        request_id:
          type: string
          format: uuid
          description: Identifier for this lookup. Quote it to support.
        data:
          type: object
          required:
            - ip
            - ip_geo
            - companies
          properties:
            ip:
              type: string
              description: The submitted IP in canonical form.
            ip_geo:
              $ref: '#/components/schemas/CompanyRevealGeography'
            companies:
              type: array
              maxItems: 10
              description: Matched companies. Empty when no company was found.
              items:
                $ref: '#/components/schemas/CompanyRevealCompany'
        usage:
          type: object
          required:
            - total_usd
            - balance_remaining_usd
          properties:
            total_usd:
              type: number
              minimum: 0
              description: >-
                Amount charged for this lookup in USD. `0` when no company was
                found.
            balance_remaining_usd:
              type: number
              description: Your available balance in USD after this lookup.
    CompanyRevealError:
      type: object
      required:
        - status
        - code
        - message
        - errors
        - timestamp
        - error_id
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: integer
          description: Equals the HTTP status code.
          enum:
            - 400
            - 401
            - 402
            - 403
            - 413
            - 415
            - 429
            - 500
            - 503
        message:
          type: string
        errors:
          type: array
          description: Field-level details where available, otherwise empty.
          items:
            type: object
            required:
              - field
              - reason
            properties:
              field:
                type: string
              reason:
                type: string
        timestamp:
          type: string
          format: date-time
        error_id:
          type: string
          format: uuid
          description: Equals the X-Request-ID header. Quote it to support.
    CompanyRevealGeography:
      type: object
      nullable: true
      description: >-
        Approximate location of the submitted IP address, not of the company.
        `null` when no location is available. IP geolocation by DB-IP
        (https://db-ip.com), licensed under CC BY 4.0.
      required:
        - city
        - state
        - country
      properties:
        city:
          type: string
          nullable: true
          description: '`null` when unknown.'
        state:
          type: string
          nullable: true
          description: '`null` when unknown.'
        country:
          type: string
          nullable: true
          description: Country name in English. `null` when unknown.
    CompanyRevealCompany:
      type: object
      required:
        - domain
        - name
        - profile_url
        - industry
        - employees_count
        - country
      properties:
        domain:
          type: string
          description: Company website domain. Always present.
        name:
          type: string
          nullable: true
        profile_url:
          type: string
          nullable: true
          description: LinkedIn company or school page URL.
        industry:
          type: string
          nullable: true
        employees_count:
          type: integer
          nullable: true
          minimum: 0
        country:
          type: string
          nullable: true
          description: Country of the company's headquarters, not of the visitor.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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