openapi: 3.0.3
info:
  title: Seamless.AI Companies Enrichment API
  description: The Seamless.AI Companies API enables programmatic search and research of company data including firmographics, revenue, employee count, technology stack, and company intelligence for sales and marketing use cases.
  version: 1.0.0
  contact:
    url: https://docs.seamless.ai/
servers:
- url: https://api.seamless.ai
  description: Seamless.AI API
security:
- apiKey: []
tags:
- name: Enrichment
paths:
  /v1/companies/enrich:
    post:
      operationId: enrichCompany
      summary: Enrich Company
      description: Enrich an existing company record with updated or missing firmographic data. Provide known company identifiers and receive back verified company information including revenue, employee count, industry classification, and technology stack.
      tags:
      - Enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyEnrichRequest'
      responses:
        '200':
          description: Enriched company data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRecord'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /v1/contacts/enrich:
    post:
      operationId: enrichContact
      summary: Enrich Contact
      description: Enrich an existing contact record with updated or missing fields. Provide known contact identifiers and receive back verified emails, direct dials, mobile numbers, job titles, and company information.
      tags:
      - Enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactEnrichRequest'
      responses:
        '200':
          description: Enriched contact data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactRecord'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
components:
  schemas:
    ContactRecord:
      type: object
      properties:
        id:
          type: string
          description: Unique contact identifier
        name:
          type: string
          description: Full name
        firstName:
          type: string
        lastName:
          type: string
        title:
          type: string
          description: Current job title
        company:
          type: string
          description: Current employer name
        emails:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
              type:
                type: string
                enum:
                - work
                - personal
              verified:
                type: boolean
        phones:
          type: array
          items:
            type: object
            properties:
              number:
                type: string
              type:
                type: string
                enum:
                - direct
                - mobile
                - office
        location:
          type: string
        linkedinUrl:
          type: string
        jobHistory:
          type: array
          items:
            type: object
            properties:
              company:
                type: string
              title:
                type: string
              startDate:
                type: string
              endDate:
                type: string
    CompanyRecord:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        domain:
          type: string
        description:
          type: string
        industry:
          type: string
        subIndustry:
          type: string
        employeeCount:
          type: integer
        revenue:
          type: number
          description: Annual revenue in USD
        founded:
          type: integer
          description: Year founded
        headquarters:
          type: object
          properties:
            city:
              type: string
            state:
              type: string
            country:
              type: string
        technologies:
          type: array
          items:
            type: string
        linkedinUrl:
          type: string
        twitterUrl:
          type: string
        facebookUrl:
          type: string
        funding:
          type: object
          properties:
            totalAmount:
              type: number
            lastRound:
              type: string
            lastRoundDate:
              type: string
              format: date
    CompanyEnrichRequest:
      type: object
      properties:
        domain:
          type: string
        companyName:
          type: string
        linkedinUrl:
          type: string
    ContactEnrichRequest:
      type: object
      properties:
        email:
          type: string
          description: Email address to enrich
        name:
          type: string
          description: Contact full name
        company:
          type: string
          description: Company name
        linkedinUrl:
          type: string
          description: LinkedIn profile URL
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key in the format "Bearer {api_key}"