openapi: 3.0.1
info:
  title: CustomerOS API
  description: CustomerOS API for multiple services (Verify, Enrich, Orgs)
  contact: {}
  version: '1.0'
servers:
- url: https://api.customeros.ai/
paths:
  /enrich/v1/organization:
    get:
      tags:
      - Enrichment API
      summary: Enrich organization information
      description: Enriches organization information using either domain or LinkedIn
        URL
      parameters:
      - name: linkedinUrl
        in: query
        description: Organization's LinkedIn URL
        schema:
          type: string
      - name: domain
        in: query
        description: Organization's domain
        schema:
          type: string
      responses:
        '200':
          description: 'Organization not found (status: warning)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '400':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
      security:
      - ApiKeyAuth: []
  /enrich/v1/person:
    get:
      tags:
      - Enrichment API
      summary: Enrich person information
      description: Enriches person information using LinkedIn URL, email, and other
        optional details
      parameters:
      - name: linkedinUrl
        in: query
        description: LinkedIn profile URL
        schema:
          type: string
      - name: email
        in: query
        description: Email address
        schema:
          type: string
          format: email
      - name: firstName
        in: query
        description: First name
        schema:
          minLength: 1
          type: string
      - name: lastName
        in: query
        description: Last name
        schema:
          minLength: 1
          type: string
      - name: includeMobileNumber
        in: query
        description: Include mobile number in results
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Person not found (status: warning)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '202':
          description: Processing initiated, check ResultURL for final data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restenrich.EnrichPersonResponse'
        '400':
          description: Missing linkedinUrl or email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
      security:
      - ApiKeyAuth: []
  /enrich/v1/person/results/{id}:
    get:
      tags:
      - Enrichment API
      summary: Retrieve enrichment results
      description: Retrieves the results of an asynchronous person enrichment operation
      parameters:
      - name: id
        in: path
        description: Result ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved enriched data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restenrich.EnrichPersonResponse'
        '202':
          description: Still processing, check again later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restenrich.EnrichPersonResponse'
        '400':
          description: Invalid result ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '404':
          description: Result not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    billing.InvoiceRecord:
      type: object
      properties:
        amount:
          type: number
          description: 'Total amount due for the invoice

            required: true

            example: 1500.50

            minimum: 0'
        currency:
          type: string
          description: 'Currency code for the invoice amount

            required: true

            example: USD

            pattern: ^[A-Z]{3}$'
        dueDate:
          type: string
          description: 'Date when the invoice payment is due

            required: true

            example: 2024-12-01T00:00:00Z

            format: date-time'
        id:
          type: string
          description: 'Unique identifier for the invoice

            required: true

            example: 123e4567-e89b-12d3-a456-426614174000

            format: uuid'
        invoiceStatus:
          type: string
          description: 'Current status of the invoice

            required: true

            example: PAID

            enum: DRAFT,PENDING,PAID,OVERDUE,CANCELLED,VOID'
        number:
          type: string
          description: 'Invoice number or reference

            required: true

            example: INV-2024-001

            minLength: 1'
        paymentLink:
          type: string
          description: 'URL where the invoice can be paid

            required: false

            example: https://payment.example.com/inv/12345

            format: uri'
        publicUrl:
          type: string
          description: 'Public URL to access the invoice PDF

            required: false

            example: https://invoices.example.com/12345.pdf

            format: uri'
      description: Detailed invoice information including payment details and status
    billing.InvoicesResponse:
      type: object
      properties:
        invoices:
          type: array
          description: 'List of invoices

            required: false'
          items:
            $ref: '#/components/schemas/billing.InvoiceRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing multiple invoices
    customerbase.BulkErrorDetails:
      type: object
      properties:
        description:
          type: string
          description: 'Description of the error

            example: invalid email format'
        value:
          type: string
          description: 'The value that caused the error

            example: invalid@email..com'
      description: Error details for failed operations in bulk processing
    customerbase.BulkResponse:
      type: object
      properties:
        details:
          type: object
          description: Error details if any
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkErrorDetails'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
        summary:
          type: object
          description: Summary of the bulk operation
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkSummary'
      description: Response structure for bulk operations with single error detail
    customerbase.BulkResponseMultipleErrors:
      type: object
      properties:
        details:
          type: array
          description: List of error details
          items:
            $ref: '#/components/schemas/customerbase.BulkErrorDetails'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
        summary:
          type: object
          description: Summary of the bulk operation
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkSummary'
      description: Response structure for bulk operations with multiple error details
    customerbase.BulkSummary:
      type: object
      properties:
        failed:
          type: integer
          description: 'Number of failed records

            example: 5'
        success:
          type: integer
          description: 'Number of successfully processed records

            example: 95'
        total:
          type: integer
          description: 'Total number of records processed

            example: 100'
      description: Summary statistics for bulk operations
    customerbase.ContactRecord:
      type: object
      properties:
        contactId:
          type: string
          description: 'Contact''s unique identifier

            example: contact-123'
        email:
          type: string
          description: 'Contact''s email address

            example: john@example.com'
        linkedinUrl:
          type: string
          description: 'Contact''s LinkedIn profile URL

            example: https://linkedin.com/in/john-doe'
      description: Request to create a contact
    customerbase.ContactsResponse:
      type: object
      properties:
        contacts:
          type: array
          description: List of contacts
          items:
            $ref: '#/components/schemas/customerbase.ContactRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response structure for multiple contact operations
    customerbase.CreateOrganizationRequest:
      type: object
      properties:
        customId:
          type: string
          description: 'Custom ID provided by the user

            example: 12345'
        icpFit:
          type: boolean
          description: 'Indicates if the organization is an ICP (Ideal Customer Profile)
            fit

            example: true'
        leadSource:
          type: string
          description: 'Lead source of the organization

            example: Web Search'
        linkedinUrl:
          type: string
          description: 'Organization''s LinkedIn profile URL

            example: https://linkedin.com/company/openline'
        name:
          type: string
          description: 'Organization''s name

            required: true

            example: CustomerOS'
        relationship:
          type: string
          description: 'Relationship status of the organization

            example: customer'
        website:
          type: string
          description: 'Organization''s website URL

            example: https://customeros.ai'
      description: Request to create an organization
    customerbase.ExternalLink:
      type: object
      properties:
        id:
          type: string
          description: 'External system identifier

            example: cos-12345'
        name:
          type: string
          description: 'External system name

            example: stripe'
        primary:
          type: boolean
          description: 'Indicates if this is the primary link

            example: true'
      description: External system link information
    customerbase.ExternalSystemRecord:
      type: object
      properties:
        externalId:
          type: string
          description: 'External system identifier

            example: stripe-1234'
        externalSystem:
          type: string
          description: 'Name of the external system

            example: stripe'
        organizationId:
          type: string
          description: 'Associated organization ID

            example: org-789'
        primary:
          type: boolean
          description: 'Indicates if this is the primary link

            example: true'
      description: External system information and its relationship to an organization
    customerbase.ExternalSystemResponse:
      type: object
      properties:
        organization:
          type: object
          description: The external system information
          allOf:
          - $ref: '#/components/schemas/customerbase.ExternalSystemRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response structure for external system operations
    customerbase.OrganizationRecord:
      type: object
      properties:
        cosId:
          type: string
          description: 'CustomerOS unique identifier

            example: C-A12-B45'
        customId:
          type: string
          description: 'Custom ID provided by the user

            example: 12345'
        domains:
          type: array
          description: 'Associated domains

            example: ["customeros.com","customeros.ai"]'
          items:
            type: string
        externalLinks:
          type: array
          description: External system links
          items:
            $ref: '#/components/schemas/customerbase.ExternalLink'
        icpFit:
          type: boolean
          description: 'ICP fit indicator

            example: true'
        id:
          type: string
          description: 'Organization''s unique identifier

            example: 123e4567-e89b-12d3-a456-426614174000'
        leadSource:
          type: string
          description: 'Lead source of the organization

            example: Web Search'
        name:
          type: string
          description: 'Organization name

            example: CustomerOS'
        relationship:
          type: string
          description: 'Relationship status with the organization

            example: customer'
        stage:
          type: string
          description: 'Current stage in the organization lifecycle

            example: lead'
        website:
          type: string
          description: 'Organization''s website URL

            example: https://customeros.ai'
      description: Detailed organization information returned by API operations
    customerbase.OrganizationResponse:
      type: object
      properties:
        organization:
          type: object
          description: The organization information
          allOf:
          - $ref: '#/components/schemas/customerbase.OrganizationRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response structure for single organization operations
    customerbase.SetPrimaryExternalSystemIdRequest:
      type: object
      properties:
        externalId:
          type: string
          description: 'The ID of the external system to be set as primary

            required: true

            example: stripe-1234'
      description: Request to set or replace the primary external system ID
    customerbase.SingleContactResponse:
      type: object
      properties:
        contact:
          type: object
          description: The contact information
          allOf:
          - $ref: '#/components/schemas/customerbase.ContactRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response structure for single contact operations
    rest.BaseResponse:
      type: object
      properties:
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Standard response structure for API operations
    rest.ErrorResponse:
      type: object
      properties:
        message:
          type: string
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
    restenrich.EnrichOrganizationData:
      type: object
      properties:
        description:
          type: string
          description: 'Brief description of the organization

            required: false

            example: A global leader in innovative solutions'
        domain:
          type: string
          description: 'Organization''s primary domain

            required: true

            example: acme.com'
        employees:
          type: integer
          description: 'Number of employees

            required: false

            minimum: 0

            example: 5000'
        foundedYear:
          type: integer
          description: 'Year the organization was founded

            required: false

            minimum: 1800

            maximum: 2100

            example: 1995'
        icons:
          type: array
          description: 'URLs to organization icons

            required: false

            example: ["https://acme.com/icon.png"]'
          items:
            type: string
        industry:
          type: object
          description: 'Industry classification

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichOrganizationIndustry'
        location:
          type: object
          description: 'Organization location information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichOrganizationLocation'
        logos:
          type: array
          description: 'URLs to organization logos

            required: false

            example: ["https://acme.com/logo.png"]'
          items:
            type: string
        longDescription:
          type: string
          description: 'Detailed description of the organization

            required: false

            example: Acme Corporation provides cutting-edge technology solutions across
            the globe'
        name:
          type: string
          description: 'Organization name

            required: true

            example: Acme Corporation'
        public:
          type: boolean
          description: 'Indicates if the organization is publicly traded

            required: false

            example: true'
        socials:
          type: array
          description: 'Social media presence

            required: false

            example: ["https://linkedin.com/company/acme"]'
          items:
            type: string
        website:
          type: string
          description: 'Organization''s website URL

            required: true

            example: https://acme.com

            format: uri'
      description: Detailed enriched information about an organization
    restenrich.EnrichOrganizationIndustry:
      type: object
      properties:
        industry:
          type: string
          description: 'Primary industry category

            required: true

            example: Technology'
      description: Industry classification information
    restenrich.EnrichOrganizationLocation:
      type: object
      properties:
        addressLine1:
          type: string
          description: 'Primary address line

            required: false

            example: 123 Main St'
        addressLine2:
          type: string
          description: 'Secondary address line

            required: false

            example: Suite 100'
        city:
          type: string
          description: 'City name

            required: false

            example: San Francisco'
        country:
          type: string
          description: 'Country name

            required: true

            example: United States'
        countryCodeA2:
          type: string
          description: 'ISO 3166-1 alpha-2 country code

            required: true

            example: US

            pattern: ^[A-Z]{2}$'
        isHeadquarter:
          type: boolean
          description: 'Indicates if this is the headquarters location

            required: true

            example: true'
        postalCode:
          type: string
          description: 'Postal code

            required: false

            example: 94105'
        region:
          type: string
          description: 'State or region

            required: false

            example: California'
      description: Detailed location information for an organization
    restenrich.EnrichOrganizationResponse:
      type: object
      properties:
        data:
          type: object
          description: 'Enriched organization data

            required: true'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichOrganizationData'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response structure for organization enrichment operations
    restenrich.EnrichPersonData:
      type: object
      properties:
        emails:
          type: array
          description: 'List of email addresses associated with the person

            required: false'
          items:
            $ref: '#/components/schemas/restenrich.EnrichPersonEmail'
        jobs:
          type: array
          description: 'Employment history

            required: false'
          items:
            $ref: '#/components/schemas/restenrich.EnrichPersonJob'
        location:
          type: object
          description: 'Geographic location information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonLocation'
        name:
          type: object
          description: 'Person''s name information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonName'
        phoneNumbers:
          type: array
          description: 'List of phone numbers

            required: false'
          items:
            $ref: '#/components/schemas/restenrich.EnrichPersonPhoneNumber'
        profilePic:
          type: string
          description: 'URL to person''s profile picture

            required: false

            format: uri'
          example: https://example.com/profile.jpg
        social:
          type: object
          description: 'Social media presence

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonSocial'
      description: Comprehensive enriched information about a person
    restenrich.EnrichPersonDiscord:
      type: object
      properties:
        username:
          type: string
          description: 'Discord username with discriminator

            required: true

            pattern: ^.{3,32}#[0-9]{4}$'
          example: johndoe#1234
      description: Discord profile details
    restenrich.EnrichPersonEmail:
      type: object
      properties:
        address:
          type: string
          description: 'Email address

            required: true

            format: email'
          example: john.doe@example.com
        deliverable:
          type: string
          description: 'Indicates if the email is deliverable

            required: false'
          example: 'true'
        isRisky:
          type: boolean
          description: 'Indicates if the email is considered risky

            required: false'
          example: false
        type:
          type: string
          description: 'Type of email address

            required: false

            enum: personal,work'
          example: work
      description: Email address with validation details
    restenrich.EnrichPersonGithub:
      type: object
      properties:
        url:
          type: string
          description: 'Full GitHub profile URL

            required: false

            format: uri'
          example: https://github.com/johndoe
        username:
          type: string
          description: 'GitHub username

            required: true'
          example: johndoe
      description: GitHub profile details
    restenrich.EnrichPersonJob:
      type: object
      properties:
        company:
          type: string
          description: 'Company name

            required: true'
          example: Tech Corp
        companyLinkedin:
          type: string
          description: 'Company''s LinkedIn URL

            required: false

            format: uri'
          example: https://linkedin.com/company/techcorp
        companyWebsite:
          type: string
          description: 'Company''s website

            required: false

            format: uri'
          example: https://techcorp.com
        duration:
          type: object
          description: 'Employment duration

            required: true'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonJobDuration'
        isCurrent:
          type: boolean
          description: 'Indicates if this is the current position

            required: true'
          example: true
        seniority:
          type: string
          description: 'Seniority level

            required: false

            enum: Junior,Mid-Level,Senior,Lead,Manager,Director,VP,C-Level'
          example: Senior
        title:
          type: string
          description: 'Job title

            required: true'
          example: Software Engineer
      description: Details about a person's job position
    restenrich.EnrichPersonJobDuration:
      type: object
      properties:
        endMonth:
          type: integer
          description: 'Ending month (1-12)

            required: false

            minimum: 1

            maximum: 12'
          example: 12
        endYear:
          type: integer
          description: 'Ending year

            required: false

            minimum: 1900

            maximum: 2100'
          example: 2023
        startMonth:
          type: integer
          description: 'Starting month (1-12)

            required: false

            minimum: 1

            maximum: 12'
          example: 1
        startYear:
          type: integer
          description: 'Starting year

            required: false

            minimum: 1900

            maximum: 2100'
          example: 2020
      description: Time period of employment
    restenrich.EnrichPersonLinkedIn:
      type: object
      properties:
        followerCount:
          type: integer
          description: 'Number of LinkedIn followers

            required: false

            minimum: 0'
          example: 500
        id:
          type: string
          description: 'LinkedIn internal ID

            required: false'
          example: '123456789'
        publicId:
          type: string
          description: 'LinkedIn public identifier

            required: false'
          example: john-doe
        url:
          type: string
          description: 'Full LinkedIn profile URL

            required: false

            format: uri'
          example: https://linkedin.com/in/john-doe
      description: LinkedIn specific profile details
    restenrich.EnrichPersonLocation:
      type: object
      properties:
        city:
          type: string
          description: 'City name

            required: false'
          example: San Francisco
        country:
          type: string
          description: 'Country name

            required: false'
          example: United States
        region:
          type: string
          description: 'State or region

            required: false'
          example: California
        timezone:
          type: string
          description: 'Timezone identifier

            required: false

            example: America/Los_Angeles'
          example: PST
      description: Geographic and timezone information about a person
    restenrich.EnrichPersonName:
      type: object
      properties:
        firstName:
          type: string
          description: 'First name

            required: true

            minLength: 1'
          example: John
        fullName:
          type: string
          description: 'Full name (typically firstName + lastName)

            required: false'
          example: John Doe
        lastName:
          type: string
          description: 'Last name

            required: true

            minLength: 1'
          example: Doe
      description: Person's name details
    restenrich.EnrichPersonPhoneNumber:
      type: object
      properties:
        number:
          type: string
          description: 'Phone number in E.164 format

            required: true

            pattern: ^\+[1-9]\d{1,14}$'
          example: '+14155552671'
        type:
          type: string
          description: 'Type of phone number

            required: true

            enum: mobile,work,home,other'
          example: mobile
      description: Phone number with type classification
    restenrich.EnrichPersonResponse:
      type: object
      properties:
        data:
          type: object
          description: 'Enriched person data

            required: true'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonData'
        isComplete:
          type: boolean
          description: 'Indicates if all enrichment operations are complete

            required: true'
          example: true
        message:
          type: string
          description: 'Optional message providing additional information

            required: false'
          example: Enrichment completed
        pendingFields:
          type: array
          description: 'List of fields still being processed

            required: false'
          example:
          - email
          - phone number
          items:
            type: string
        resultUrl:
          type: string
          description: 'URL to check the final result when processing is incomplete

            required: false

            format: uri'
          example: https://api.customeros.ai/enrich/v1/person/results/550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: 'Operation status

            required: true

            enum: success,error,warning'
          example: success
      description: Response structure for person enrichment operations
    restenrich.EnrichPersonSocial:
      type: object
      properties:
        discord:
          type: object
          description: 'Discord profile information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonDiscord'
        github:
          type: object
          description: 'GitHub profile information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonGithub'
        linkedin:
          type: object
          description: 'LinkedIn profile information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonLinkedIn'
        x:
          type: object
          description: 'X (Twitter) profile information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restenrich.EnrichPersonX'
      description: Collection of social media profile information
    restenrich.EnrichPersonX:
      type: object
      properties:
        handle:
          type: string
          description: 'X handle (without @)

            required: true'
          example: johndoe
        url:
          type: string
          description: 'Full X profile URL

            required: false

            format: uri'
          example: https://x.com/johndoe
      description: X (formerly Twitter) profile details
    restmailstack.ConfigureDomainRequest:
      type: object
      properties:
        domain:
          type: string
          description: 'Domain name to configure

            required: true

            pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[a-zA-Z]{2,}$

            example: example.com'
        website:
          type: string
          description: 'Website URL for domain configuration

            required: true

            format: uri

            example: https://www.example.com'
      description: Request payload for configuring domain DNS and mail services
    restmailstack.DomainRecord:
      type: object
      properties:
        createdDate:
          type: string
          description: 'Domain registration date

            required: true

            format: date

            example: 2024-09-14'
        domain:
          type: string
          description: 'Registered domain name

            required: true

            example: example.com'
        expiredDate:
          type: string
          description: 'Domain expiration date

            required: true

            format: date

            example: 2025-09-14'
        nameservers:
          type: array
          description: 'List of assigned nameservers

            required: true

            minItems: 2

            example: ["ns1.example.com","ns2.example.com"]'
          items:
            type: string
      description: Comprehensive domain record information
    restmailstack.DomainResponse:
      type: object
      properties:
        domain:
          type: object
          description: 'Domain information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restmailstack.DomainRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing domain details and status
    restmailstack.DomainsResponse:
      type: object
      properties:
        domains:
          type: array
          description: 'List of domains

            required: true'
          items:
            $ref: '#/components/schemas/restmailstack.DomainRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing list of domains and status
    restmailstack.MailboxRecord:
      type: object
      properties:
        email:
          type: string
          description: 'Email address for the mailbox

            required: true

            format: email

            example: user@example.com'
        forwardingEnabled:
          type: boolean
          description: 'Email forwarding status

            required: true

            default: false'
        forwardingTo:
          type: array
          description: 'List of forwarding email addresses

            required: false

            maxItems: 10'
          items:
            type: string
        password:
          type: string
          description: 'Mailbox password (only included in specific responses)

            required: false

            minLength: 8

            maxLength: 64'
        webmailEnabled:
          type: boolean
          description: 'Webmail access status

            required: true

            default: false'
      description: Comprehensive mailbox configuration and status
    restmailstack.MailboxRequest:
      type: object
      properties:
        forwardingTo:
          type: array
          description: 'List of email addresses to forward to

            required: false

            maxItems: 10

            example: ["user1@example.com","user2@example.com"]'
          items:
            type: string
        linkedUser:
          type: string
          description: 'Associated user''s email address

            required: false

            format: email

            example: john.doe@mycompany.com'
        password:
          type: string
          description: 'Password for mailbox access

            required: false

            minLength: 8

            maxLength: 64

            example: SecurePassword123!'
        username:
          type: string
          description: 'Username for the mailbox

            required: true

            pattern: ^[a-zA-Z0-9._%+-]+$

            minLength: 3

            maxLength: 64

            example: john.doe'
        webmailEnabled:
          type: boolean
          description: 'Enable webmail access

            required: false

            default: false'
      description: Request payload for creating and configuring a new mailbox
    restmailstack.MailboxResponse:
      type: object
      properties:
        mailbox:
          type: object
          description: 'Mailbox information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restmailstack.MailboxRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing mailbox details and status
    restmailstack.MailboxesResponse:
      type: object
      properties:
        mailboxes:
          type: array
          description: 'List of mailboxes

            required: false'
          items:
            $ref: '#/components/schemas/restmailstack.MailboxRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing list of mailboxes and status
    restmailstack.RegisterNewDomainRequest:
      type: object
      properties:
        domain:
          type: string
          description: 'Domain name to register

            required: true

            pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[a-zA-Z]{2,}$

            example: example.com'
        website:
          type: string
          description: 'Website URL for domain configuration

            required: true

            format: uri

            example: https://www.example.com'
      description: Request payload for registering a new domain for mail services
    restoutreach.EmailTrackingRequest:
      type: object
      properties:
        campaignId:
          type: string
          description: 'Unique identifier for the email campaign

            required: true

            example: camp_123456'
        generateUnsubscribeLink:
          type: boolean
          description: 'Enable unsubscribe link generation

            required: false

            default: false'
        links:
          type: array
          description: 'List of URLs to be tracked

            required: false

            example: ["https://example.com/page1", "https://example.com/page2"]'
          items:
            type: string
        messageId:
          type: string
          description: 'Unique identifier for the message (optional, generated if
            not provided)

            required: false

            example: msg_123456'
        recipientId:
          type: string
          description: 'Unique identifier for the recipient

            required: true

            example: recipient_123456'
        trackClicks:
          type: boolean
          description: 'Enable click tracking for links

            required: false

            default: false'
        trackOpens:
          type: boolean
          description: 'Enable open tracking via pixel

            required: false

            default: false'
        trackerDomain:
          type: string
          description: 'Domain to use for tracking URLs (optional, system default
            used if not provided)

            required: false

            format: hostname

            example: track.example.com'
        unsubscribeLink:
          type: string
          description: 'URL for unsubscribe page

            required: false

            format: uri

            example: https://example.com/unsubscribe'
      description: Request payload for generating email tracking URLs and pixels
    restoutreach.EmailTrackingResponse:
      type: object
      properties:
        status:
          type: string
          description: 'Operation status

            required: true

            enum: success'
          example: success
        trackedLinks:
          type: array
          description: 'List of original and tracked URLs (only if TrackClicks is
            true)

            required: false'
          items:
            $ref: '#/components/schemas/restoutreach.TrackedLink'
        trackingId:
          type: string
          description: 'Generated or provided message ID

            required: true'
          example: msg_123456
        trackingPixel:
          type: string
          description: 'URL for tracking pixel (only if TrackOpens is true)

            required: false

            format: uri'
          example: https://track.example.com/p/abc123
        unsubscribeLink:
          type: string
          description: 'Generated unsubscribe link (only if GenerateUnsubscribeLink
            is true)

            required: false

            format: uri'
          example: https://track.example.com/u/abc123
      description: Response containing generated tracking URLs and pixel
    restoutreach.TrackedLink:
      type: object
      properties:
        original:
          type: string
          description: 'Original URL before tracking

            required: true

            format: uri'
          example: https://example.com/page1
        tracked:
          type: string
          description: 'Generated tracking URL

            required: true

            format: uri'
          example: https://track.example.com/r/abc123
      description: Pair of original and tracking-enabled URLs
    restverify.BulkResultsDetails:
      type: object
      properties:
        deliverable:
          type: integer
          description: 'Number of deliverable emails

            required: true

            minimum: 0'
          example: 950
        downloadUrl:
          type: string
          description: 'URL to download detailed results

            required: true

            format: uri'
          example: https://api.customeros.ai/verify/v1/email/bulk/results/550e8400-e29b-41d4-a716-446655440000/download
        totalEmails:
          type: integer
          description: 'Total number of emails processed

            required: true

            minimum: 0'
          example: 1000
        undeliverable:
          type: integer
          description: 'Number of undeliverable emails

            required: true

            minimum: 0'
          example: 45
      description: Detailed statistics for bulk verification results
    restverify.BulkResultsResponse:
      type: object
      properties:
        estimatedCompletionTs:
          type: integer
          description: 'Estimated completion timestamp

            required: true'
          example: 1694030400
        fileName:
          type: string
          description: 'Original filename

            required: true'
          example: emails.csv
        jobId:
          type: string
          description: 'Unique job identifier

            required: true

            format: uuid'
          example: 550e8400-e29b-41d4-a716-446655440000
        message:
          type: string
          description: 'Progress message

            required: true'
          example: Completed 1000 of 1000 emails
        results:
          type: object
          description: 'Verification results if completed

            required: false'
          allOf:
          - $ref: '#/components/schemas/restverify.BulkResultsDetails'
        status:
          type: string
          description: 'Processing status

            required: true

            enum: processing,completed'
          example: completed
      description: Response containing bulk verification results or status
    restverify.BulkUploadResponse:
      type: object
      properties:
        estimatedCompletionTs:
          type: number
          description: 'Estimated completion timestamp

            required: true'
          example: 1694030400
        jobId:
          type: string
          description: 'Unique job identifier

            required: true

            format: uuid'
          example: 550e8400-e29b-41d4-a716-446655440000
        message:
          type: string
          description: 'Status message

            required: true'
          example: File uploaded successfully
        resultUrl:
          type: string
          description: 'URL to check verification results

            required: true

            format: uri'
          example: https://api.customeros.ai/verify/v1/email/bulk/results/550e8400-e29b-41d4-a716-446655440000
      description: Response after initiating bulk email verification
    restverify.EmailVerificationRecord:
      type: object
      properties:
        alternateEmail:
          type: string
          description: 'Alternative email address if available

            required: false

            format: email'
          example: alternate@example.com
        deliverable:
          type: string
          description: 'Deliverability status

            required: true

            enum: true,false,unknown'
          example: 'true'
        emailAddress:
          type: string
          description: 'Email address that was verified

            required: true

            format: email'
          example: example@example.com
        isCatchAll:
          type: boolean
          description: 'Indicates if domain is catch-all

            required: true'
          example: false
        isRisky:
          type: boolean
          description: 'Indicates if email is considered risky

            required: true'
          example: false
        provider:
          type: string
          description: 'Email service provider

            required: false'
          example: gmail
        risk:
          type: object
          description: 'Risk assessment details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationRisk'
        secureGatewayProvider:
          type: string
          description: 'Security gateway provider

            required: false'
          example: Proofpoint
        syntax:
          type: object
          description: 'Syntax validation details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationSyntax'
      description: Detailed validation results for an email address
    restverify.EmailVerificationResponse:
      type: object
      properties:
        email:
          type: object
          description: 'Email verification details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response for single email verification including detailed validation
        results
    restverify.EmailVerificationRisk:
      type: object
      properties:
        isFirewalled:
          type: boolean
          description: 'Indicates if email is behind a firewall

            required: true'
          example: false
        isFreeProvider:
          type: boolean
          description: 'Indicates if email uses a free provider

            required: true'
          example: true
        isMailboxFull:
          type: boolean
          description: 'Indicates if mailbox is full

            required: true'
          example: false
        isPrimaryDomain:
          type: boolean
          description: 'Indicates if domain is primary

            required: true'
          example: true
        isRoleMailbox:
          type: boolean
          description: 'Indicates if email is a role account

            required: true'
          example: false
        isSystemGenerated:
          type: boolean
          description: 'Indicates if email is system-generated

            required: true'
          example: false
      description: Risk factors associated with the email address
    restverify.EmailVerificationSyntax:
      type: object
      properties:
        domain:
          type: string
          description: 'Domain part of email

            required: true'
          example: example.com
        isValid:
          type: boolean
          description: 'Indicates if email syntax is valid

            required: true'
          example: true
        user:
          type: string
          description: 'Local part of email

            required: true'
          example: example
      description: Email syntax validation details
    restverify.IpIntelligenceGeolocation:
      type: object
      properties:
        city:
          type: string
          description: 'City name

            required: false'
          example: Berlin
        country:
          type: string
          description: 'Country name

            required: true'
          example: Germany
        countryIso:
          type: string
          description: 'ISO 3166-1 alpha-2 country code

            required: true

            pattern: ^[A-Z]{2}$'
          example: DE
        isEuropeanUnion:
          type: boolean
          description: 'Indicates if country is in the European Union

            required: true'
          example: true
      description: Geographic location information for the IP address
    restverify.IpIntelligenceNetwork:
      type: object
      properties:
        asn:
          type: string
          description: 'Autonomous System Number

            required: true

            pattern: ^AS\d+$'
          example: AS12345
        domain:
          type: string
          description: 'Network domain

            required: false'
          example: isp.com
        name:
          type: string
          description: 'Network name

            required: true'
          example: ISP Name
        route:
          type: string
          description: 'Network route (CIDR notation)

            required: true

            pattern: ^(\d{1,3}\.){3}\d{1,3}/\d{1,2}$'
          example: 192.168.0.0/16
        type:
          type: string
          description: 'Network type

            required: true

            enum: business,hosting,isp,education,government'
          example: business
      description: Network information for the IP address
    restverify.IpIntelligenceOrganization:
      type: object
      properties:
        domain:
          type: string
          description: 'Organization domain

            required: false'
          example: company.com
        linkedin:
          type: string
          description: 'LinkedIn profile URL

            required: false

            format: uri'
          example: https://linkedin.com/company/company
        name:
          type: string
          description: 'Organization name

            required: false'
          example: Company Name
      description: Organization information associated with the IP address
    restverify.IpIntelligenceRecord:
      type: object
      properties:
        geolocation:
          type: object
          description: 'Geolocation information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceGeolocation'
        ipAddress:
          type: string
          description: 'IP address being analyzed

            required: true

            pattern: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
          example: 192.168.1.1
        network:
          type: object
          description: 'Network information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceNetwork'
        organization:
          type: object
          description: 'Organization information

            required: false'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceOrganization'
        threats:
          type: object
          description: 'Threat intelligence information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceThreats'
        time_zone:
          type: object
          description: 'Timezone information

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceTimeZone'
      description: Comprehensive information about an IP address
    restverify.IpIntelligenceResponse:
      type: object
      properties:
        ip:
          type: object
          description: 'IP intelligence details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.IpIntelligenceRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or
            "error")
          example: success
      description: Response containing IP intelligence data including threats, geolocation,
        and network information
    restverify.IpIntelligenceThreats:
      type: object
      properties:
        isCloudRelay:
          type: boolean
          description: 'Indicates if IP is a cloud relay

            required: true'
          example: false
        isDatacenter:
          type: boolean
          description: 'Indicates if IP belongs to a datacenter

            required: true'
          example: false
        isMobile:
          type: boolean
          description: 'Indicates if IP belongs to a mobile network

            required: true'
          example: false
        isProxy:
          type: boolean
          description: 'Indicates if IP is a proxy

            required: true'
          example: false
        isTor:
          type: boolean
          description: 'Indicates if IP is a TOR exit node

            required: true'
          example: false
        isUnallocated:
          type: boolean
          description: 'Indicates if IP is unallocated

            required: true'
          example: false
        isVpn:
          type: boolean
          description: 'Indicates if IP is a VPN

            required: true'
          example: false
      description: Threat intelligence indicators for the IP address
    restverify.IpIntelligenceTimeZone:
      type: object
      properties:
        abbr:
          type: string
          description: 'Timezone abbreviation

            required: true

            example: CET'
        current_time:
          type: string
          description: 'Current time in the timezone

            required: true

            format: date-time'
          example: '2024-09-10T14:00:00+01:00'
        is_dst:
          type: boolean
          description: 'Indicates if daylight saving time is active

            required: true'
          example: true
        name:
          type: string
          description: 'IANA timezone name

            required: true

            example: Europe/Berlin'
        offset:
          type: string
          description: 'UTC offset

            required: true

            pattern: ^[+-]\d{4}$'
          example: '+0100'
      description: Timezone information for the IP address location
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-CUSTOMER-OS-API-KEY
      in: header
x-original-swagger-version: '2.0'