openapi: 3.1.0
info:
  title: Revealed Employee Finder API
  description: >-
    API for finding employee contact information from companies using various
    criteria.
  version: 1.0.0
  contact:
    name: API Support
    email: api-support@revealead.com
  license:
    name: Proprietary
    url: https://revealead.com/terms
servers:
  - url: https://api.revealead.app/employeefinder
    description: Production Server
security:
  - ApiKeyHeader: []
  - ApiKeyQuery: []
paths:
  /companies:
    get:
      summary: Search Companies
      description: >-
        Search for companies containing contacts matching specified criteria
        (seniority, department, etc.).
      operationId: searchCompanies
      tags:
        - Companies
      parameters:
        - name: contact_level_code
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - EXECUTIVE
                - DIRECTOR
                - MANAGER
                - SUPERVISOR
                - ASSISTANT
                - COLLABORATOR
                - OTHER
          style: form
          explode: true
          description: Filter by contact seniority level(s).
        - name: contact_domain_code
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: >-
            Filter by department/domain (e.g., 'IT', 'Marketing', 'Sales').
            Supports custom text.
        - name: contact_role_query
          in: query
          schema:
            type: string
          description: Semantic search query for job titles (e.g., "python developer").
        - name: email_test_status
          in: query
          schema:
            type: string
            enum:
              - all
              - safe
              - notsafe
            default: all
          description: Filter by email verification status.
        - name: contact_source
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - linkedin
                - legal
          style: form
          explode: true
          description: Filter by origin of contact data.
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Number of results per page.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination (obtained from previous response meta).
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  meta:
                    $ref: '#/components/schemas/Meta'
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        registration_number:
                          type: string
                        contacts_count:
                          type: integer
                        contacts_preview:
                          type: array
                          items:
                            $ref: '#/components/schemas/ContactPreview'
        '400':
          description: Invalid parameters
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized (Invalid or missing API key)
  /contacts/company/{company_id}:
    get:
      summary: Get Contacts by Company
      description: >-
        Retrieve contacts for a specific company using its ID or Registration
        Number.
      operationId: getContactsByCompany
      tags:
        - Contacts
      parameters:
        - name: company_id
          in: path
          required: true
          schema:
            type: string
          description: >-
            The internal Company ID OR the official Registration Number (e.g.,
            GB06441592).
        - name: show_all_anonymized
          in: query
          schema:
            type: boolean
            default: false
          description: If true, returns anonymized preview data (free of charge).
        - name: withemail
          in: query
          schema:
            type: boolean
          description: Filter Include only contacts with email addresses.
        - name: withlinkedin
          in: query
          schema:
            type: boolean
          description: Filter Include only contacts with LinkedIn URLs.
        - name: withlegal
          in: query
          schema:
            type: boolean
          description: Filter Include only legal representatives.
        - name: email_test_status
          in: query
          schema:
            type: string
            enum:
              - all
              - safe
              - notsafe
            default: all
          description: Filter by email verification status.
        - name: contact_max
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Maximum number of contacts to return.
        - name: contact_ids
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: List of specific Contact IDs to retrieve (overrides filters).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  company:
                    $ref: '#/components/schemas/Company'
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  contacts_count:
                    type: integer
                  meta:
                    type: object
                    properties:
                      has_more:
                        type: boolean
                      next_cursor:
                        type:
                          - string
                          - 'null'
                  credits_used:
                    type: integer
                    description: Number of credits consumed by this request.
        '404':
          description: Company not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /contacts/{contact_id}:
    get:
      summary: Get Single Contact
      description: Retrieve details for a single contact by their ID.
      operationId: getContact
      tags:
        - Contacts
      parameters:
        - name: contact_id
          in: path
          required: true
          schema:
            type: string
          description: The unique ID of the contact.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  contact:
                    $ref: '#/components/schemas/Contact'
                  credits_used:
                    type: integer
                    example: 1
        '404':
          description: Contact not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /health:
    get:
      summary: Health Check
      description: Check the status of the API service.
      operationId: healthCheck
      tags:
        - System
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  version:
                    type: string
                    example: 1.0.0
                  timestamp:
                    type: string
                  dependencies:
                    type: object
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: key
  schemas:
    Meta:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        next_cursor:
          type:
            - string
            - 'null'
        has_more:
          type: boolean
    Company:
      type: object
      properties:
        id:
          type: string
          description: Unique company identifier.
          example: 593b6fa6b3a2feb79d4f9f39
        registration_number:
          type: string
          description: Official registration number (e.g. SIREN).
          example: GB06441592
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique contact identifier (safe string).
          example: '8301343831281918940'
        civility:
          type: string
          example: Mr
        first_name:
          type: string
          example: James
        last_name:
          type: string
          example: THOMPSON
        role:
          type: string
          description: Job title.
          example: Chief Technology Officer
        level_code:
          type: string
          enum:
            - EXECUTIVE
            - DIRECTOR
            - MANAGER
            - SUPERVISOR
            - ASSISTANT
            - COLLABORATOR
            - OTHER
          example: DIRECTOR
        level_label:
          type: string
          example: Director
        domain_code:
          type: string
          description: Department/Domain code (any text).
          example: TECH
        domain_label:
          type: string
          example: Technology
        email:
          type: string
          format: email
          example: james.thompson@example.com
        email_test_result:
          type: string
          enum:
            - Safe to Send
            - Risky
            - Invalid
            - Unknown
          example: Safe to Send
        linkedin_url:
          type: string
          format: uri
          example: https://www.linkedin.com/in/james-thompson
        contact_source:
          type: string
          enum:
            - linkedin
            - legal
          example: linkedin
        anonymized:
          type: boolean
          description: Whether the contact data is masked (preview mode).
          example: false
    ContactPreview:
      type: object
      description: Simplified contact object for search results.
      properties:
        id:
          type: string
          example: '8301343831281918940'
        role:
          type: string
          example: CTO
        level_code:
          type: string
          example: EXECUTIVE
        domain_code:
          type: string
          example: TECH
        email_test_result:
          type: string
          example: Safe to Send
        anonymized:
          type: boolean
          example: true
    Problem:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: INVALID_PARAMETER
            message:
              type: string
              example: Invalid level_code
