> ## 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.

# Create Company Radar

> Create a company radar with company-specific filters.

<Note>
  **`updates_since`**: If omitted, the radar's creation time is used as the eligibility cutoff — your first run will likely return no results. Set it to 24–48 hours ago to receive immediate data, e.g. `2026-08-26T00:00:00Z`. `new_hires` and `promotions` radars always look from the start of the current calendar month regardless of this value.
</Note>


## OpenAPI

````yaml api_specs.yaml POST /v1/radars/companies
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/radars/companies:
    post:
      tags:
        - Radars
      summary: Create a company radar
      description: >-
        Creates a company-based radar for tracking activities at a specific
        domain. Supports filtering by departments, seniorities, and job titles.
        Each domain can only have one radar of each type per account.
      operationId: createCompanyRadar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
                - radar_type
              properties:
                domain:
                  type: string
                  description: >-
                    The domain to track (e.g., stripe.com). Protocol, www,
                    paths, and query parameters are automatically normalized.
                  example: stripe.com
                radar_type:
                  type: string
                  description: The type of company activity to track
                  enum:
                    - company_new_hires
                    - company_job_openings
                    - company_promotions
                    - company_reviews
                    - company_mentions
                    - company_social_posts
                    - company_social_posts_cxo
                    - company_social_engagements
                webhook_url:
                  type: string
                  format: uri
                  description: >-
                    Webhook URL to receive radar updates and notifications.
                    Optional — if omitted, the radar is poll-only and updates
                    are available via GET /v1/updates.
                  example: https://webhook.site/your-webhook-id
                updates_since:
                  type: string
                  format: date-time
                  description: >-
                    Optional RFC 3339 timestamp with a UTC offset defining the
                    earliest eligible source event. TAMradar normalizes and
                    stores the value in UTC. It must represent now or a past
                    instant and may be at most five calendar years old. A
                    five-second server tolerance exists only for clock skew; it
                    is not future scheduling. When omitted, the radar creation
                    timestamp is used as the effective cutoff.
                include_historical:
                  type: boolean
                  deprecated: true
                  description: >-
                    Deprecated compatibility field. It is accepted and stored
                    but has no effect. Use updates_since to request historical
                    eligibility.
                departments:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional array of department names to filter results. See
                    API documentation for valid department values.
                  example:
                    - Engineering
                    - Product Management
                    - Sales
                seniorities:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional array of seniority levels to filter results. See
                    API documentation for valid seniority values.
                  example:
                    - Senior
                    - Manager
                    - Director
                job_titles:
                  type: string
                  description: >-
                    Boolean expression filtering company radar results by job
                    title. When provided, job_titles takes precedence over
                    departments and seniorities; those fields do not affect
                    matching. Operators AND, OR, and NOT must be uppercase. A
                    single word may be unquoted; multi-word phrases must use
                    double quotes. Matching is case-insensitive for title terms.
                    A quoted phrase means contiguous phrase containment within
                    the candidate title, not exact whole-title equality:
                    "Marketing Manager" matches "Senior Marketing Manager" but
                    not "Marketing Operations Manager". EXACT("Marketing
                    Manager") requires the complete normalized title to equal
                    "Marketing Manager"; it does not match "Senior Marketing
                    Manager" and does not expand aliases or abbreviations. EXACT
                    must be uppercase and requires exactly one double-quoted
                    title. Operator precedence is NOT, then AND, then OR;
                    parentheses control grouping. Each term must contain at
                    least two searchable characters and may contain at most 100
                    characters. The complete expression may contain at most
                    9,000 characters and 32 nested Boolean groups. A malformed
                    expression returns HTTP 400 with an actionable job_titles
                    error.
                  example: >-
                    EXACT("Sales Operations Manager") OR ("sales operations" AND
                    (manager OR VP))
                custom_fields:
                  type: object
                  description: >-
                    Optional metadata to attach to this radar. Values must be
                    strings only. Use for internal tracking like account_id,
                    customer_id, or campaign_id. Returned with every webhook.
                  additionalProperties: true
                  example:
                    campaign_id: q4-2024-hiring
                    priority: high
                    customer_id: cust_123
                profile_url:
                  type: string
                  format: uri
                  description: >-
                    LinkedIn company or school page URL. Must be exact format:
                    https://www.linkedin.com/company/acme or
                    https://www.linkedin.com/school/stanford-university
                  example: https://www.linkedin.com/company/stripe
            example:
              domain: stripe.com
              radar_type: company_new_hires
              webhook_url: https://webhook.site/your-webhook-id
              departments:
                - Engineering
                - Product Management
              seniorities:
                - Senior
                - Manager
              profile_url: https://www.linkedin.com/company/stripe
              custom_fields:
                campaign_id: q4-2024-hiring
                priority: high
      responses:
        '201':
          description: Radar created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  code:
                    type: integer
                    enum:
                      - 201
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      radar_id:
                        type: string
                        format: uuid
                      radar_type:
                        type: string
                      domain:
                        type: string
                      webhook_url:
                        type: string
                        format: uri
                      radar_status:
                        type: string
                        enum:
                          - active
                        default: active
                      created_at:
                        type: string
                        format: date-time
                      updates_since:
                        type: string
                        format: date-time
                        nullable: true
                        description: >-
                          Stored customer-supplied eligibility cutoff normalized
                          to UTC. Null when omitted; in that case created_at is
                          the effective cutoff.
                      deactivated_at:
                        type: string
                        format: date-time
                        nullable: true
                      next_charge_at:
                        type: string
                        format: date-time
                        nullable: true
                      custom_fields:
                        type: object
                      departments:
                        type: array
                        items:
                          type: string
                        description: >-
                          Department filters applied to this radar. Only
                          returned if provided in request.
                      seniorities:
                        type: array
                        items:
                          type: string
                        description: >-
                          Seniority filters applied to this radar. Only returned
                          if provided in request.
                      job_titles:
                        type: string
                        description: >-
                          Job title filter applied to this radar. Only returned
                          if provided in request.
                      profile_url:
                        type: string
                        format: uri
                        description: >-
                          LinkedIn company page URL. Only returned if provided
                          in request.
                  timestamp:
                    type: string
                    format: date-time
              example:
                status: success
                code: 201
                timestamp: '2024-03-20T10:15:30.000Z'
                message: Radar created successfully
                data:
                  radar_id: 759199a6-5817-4a7d-b812-66abe65f3ce2
                  radar_type: company_new_hires
                  domain: stripe.com
                  webhook_url: https://webhook.site/your-webhook-id
                  radar_status: active
                  created_at: '2024-03-20T10:15:30.000Z'
                  deactivated_at: null
                  next_charge_at: '2024-04-20T10:15:30.000Z'
                  custom_fields:
                    campaign_id: q4-2024-hiring
                    priority: high
                  departments:
                    - Engineering
                    - Product Management
                  seniorities:
                    - Senior
                    - Manager
                  profile_url: https://www.linkedin.com/company/stripe
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  code:
                    type: integer
                    enum:
                      - 400
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        reason:
                          type: string
              examples:
                invalid_domain:
                  summary: Invalid domain format
                  value:
                    status: error
                    code: 400
                    message: Invalid request body
                    errors:
                      - field: domain
                        reason: >-
                          Invalid domain format. Please provide a valid domain
                          (e.g., example.com)
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
                forbidden_domain:
                  summary: >-
                    Domain not supported (reserved, link shortener, parked,
                    etc.)
                  value:
                    status: error
                    code: 400
                    message: Domain not supported
                    errors:
                      - field: domain
                        reason: >-
                          This domain is not supported. It may be a link
                          shortener, reserved domain, inactive domain, or
                          otherwise not trackable. Please provide the real
                          website domain you want to monitor.
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
                invalid_department:
                  summary: Invalid department values
                  value:
                    status: error
                    code: 400
                    message: Invalid filters
                    errors:
                      - field: departments
                        reason: >-
                          Invalid department(s): InvalidDept. Valid values:
                          Accounting, Administrative, Business Development,
                          Consulting, Customer Success, Design, Education,
                          Engineering, Finance, Human Resources, Information
                          Technology, Legal, Manufacturing, Marketing, Media and
                          Communication, Operations, Product Management, Project
                          Management, Purchasing, Quality Assurance, Real
                          Estate, Research, Sales, Support
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
                invalid_profile_url:
                  summary: Invalid profile_url format
                  value:
                    status: error
                    code: 400
                    message: Invalid request body
                    errors:
                      - field: profile_url
                        reason: >-
                          profile_url: Invalid LinkedIn company URL format. Must
                          be exactly: https://www.linkedin.com/company/acme or
                          https://www.linkedin.com/school/stanford-university
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '401':
          description: Authentication required - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_api_key:
                  summary: Missing API key
                  value:
                    status: error
                    code: 401
                    message: Missing API key
                    errors:
                      - field: x-api-key
                        reason: API key is required
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
                invalid_api_key:
                  summary: Invalid API key format
                  value:
                    status: error
                    code: 401
                    message: Invalid API key format
                    errors:
                      - field: x-api-key
                        reason: Invalid API key format
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '402':
          description: Payment Required - Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_balance:
                  summary: Insufficient balance
                  value:
                    status: error
                    code: 402
                    message: Insufficient balance
                    errors:
                      - field: balance
                        reason: You do not have enough balance to create this radar.
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '403':
          description: Forbidden - Valid API key but insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    status: error
                    code: 403
                    message: Insufficient permissions
                    errors:
                      - field: permission
                        reason: Your API key does not have permission to create radars
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '409':
          description: Conflict - radar already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  code:
                    type: integer
                    enum:
                      - 409
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        reason:
                          type: string
              examples:
                duplicate_radar:
                  summary: Radar already exists
                  value:
                    status: error
                    code: 409
                    message: 'Conflict: Radar already exists'
                    errors:
                      - field: domain
                        reason: >-
                          A radar with this domain and type already exists for
                          your account. Conflicting radar_id:
                          7e3dda58-a046-4746-8247-258b6fd9c3ac. You can view it
                          using GET /v1/radars/{radar_id}
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '429':
          description: >-
            Rate limit exceeded — no operation was performed. Check
            `Retry-After` to know when to retry, or `X-RateLimit-Remaining` to
            know your current budget.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until your budget is restored
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Your per-minute budget for this endpoint
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Tokens remaining right now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                minute_limit:
                  summary: Per-minute budget exhausted
                  value:
                    status: error
                    code: 429
                    message: Per-minute rate limit exceeded. Retry after 45 seconds.
                    errors:
                      - field: rate_limit
                        reason: minute
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
                burst_limit:
                  summary: Per-second burst limit hit
                  value:
                    status: error
                    code: 429
                    message: Per-second burst limit exceeded. Retry after 1 second.
                    errors:
                      - field: rate_limit
                        reason: burst
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server_error:
                  summary: Internal server error
                  value:
                    status: error
                    code: 500
                    message: An internal server error occurred.
                    errors: []
                    timestamp: '2024-03-20T10:15:30.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - status
        - code
        - message
        - errors
        - timestamp
        - error_id
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: integer
          enum:
            - 400
            - 401
            - 402
            - 403
            - 404
            - 409
            - 429
            - 500
            - 503
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            required:
              - field
              - reason
            properties:
              field:
                type: string
              reason:
                type: string
              conflicting_radar_id:
                type: string
                format: uuid
                nullable: true
        timestamp:
          type: string
          format: date-time
        error_id:
          type: string
          format: uuid
  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.