openapi: 3.0.3
info:
  title: Seamless.AI Companies Contacts 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: Contacts
paths:
  /v1/contacts/search:
    post:
      operationId: searchContacts
      summary: Search Contacts
      description: Search for B2B contacts using criteria such as name, company, title, location, industry, and other filters. Returns paginated search results with contact identifiers that can be used for enrichment.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSearchRequest'
      responses:
        '200':
          description: Successful contact search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSearchResponse'
        '401':
          description: Unauthorized - invalid or missing API key
        '429':
          description: Rate limit exceeded - 60 requests per minute per endpoint
  /v1/contacts/research:
    post:
      operationId: researchContact
      summary: Research Contact
      description: Research a specific contact using a search result ID from /contacts/search or a direct contact identifier. Returns full contact data including verified email addresses, phone numbers, job history, and social profiles.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactResearchRequest'
      responses:
        '200':
          description: Full contact research data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactRecord'
        '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:
      - Contacts
      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
  /v1/contacts/job-changes:
    get:
      operationId: listContactJobChanges
      summary: List Contact Job Changes
      description: Retrieve contacts that have recently changed jobs within your contact database. Returns job-change intelligence including previous and current roles to help identify warm outreach opportunities.
      tags:
      - Contacts
      parameters:
      - name: page
        in: query
        description: Page number for paginated results
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of results per page (max 100)
        schema:
          type: integer
          default: 25
          maximum: 100
      - name: days
        in: query
        description: Number of days to look back for job changes
        schema:
          type: integer
          default: 30
      responses:
        '200':
          description: List of contacts with recent job changes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobChangesResponse'
        '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
    ContactSearchRequest:
      type: object
      properties:
        name:
          type: string
          description: Contact full name or partial name
        company:
          type: string
          description: Company name to filter contacts
        title:
          type: string
          description: Job title or keyword
        location:
          type: string
          description: City, state, or country
        industry:
          type: string
          description: Industry vertical
        page:
          type: integer
          default: 1
          description: Page number for pagination
        per_page:
          type: integer
          default: 25
          maximum: 100
          description: Results per page
    ContactResearchRequest:
      type: object
      properties:
        searchResultId:
          type: string
          description: Search result ID from /contacts/search
        email:
          type: string
          description: Known email address for lookup
        linkedinUrl:
          type: string
          description: LinkedIn profile URL
    ContactSearchResult:
      type: object
      properties:
        searchResultId:
          type: string
          description: Unique identifier for use in research/enrichment calls
        name:
          type: string
          description: Contact full name
        company:
          type: string
          description: Current employer
        title:
          type: string
          description: Current job title
        location:
          type: string
          description: Geographic location
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
    JobChangesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              contactId:
                type: string
              name:
                type: string
              previousCompany:
                type: string
              previousTitle:
                type: string
              currentCompany:
                type: string
              currentTitle:
                type: string
              changeDate:
                type: string
                format: date
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ContactSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContactSearchResult'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        supplementalData:
          type: object
          properties:
            nextToken:
              type: string
              description: Token for next page of results
    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}"