CustomerOS REST API

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:
  /customerbase/v1/contacts:
    post:
      tags:
      - CustomerBASE API
      summary: Create a new contact
      description: Creates a contact from either JSON or CSV upload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: CSV file with contact data
                  format: binary
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: CSV file with contact data
                  format: binary
      responses:
        '200':
          description: Successfully created single contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.SingleContactResponse'
        '201':
          description: Successfully processed CSV file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.ContactsResponse'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized
          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: []
      x-codegen-request-body-name: contact
  /customerbase/v1/contacts/bulk:
    post:
      tags:
      - CustomerBASE API
      summary: Create multiple contacts
      description: Creates multiple contacts from JSON input
      requestBody:
        description: Array of contacts to create
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/customerbase.ContactRecord'
        required: true
      responses:
        '201':
          description: All contacts created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.BulkResponse'
        '207':
          description: Contacts created with some failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.BulkResponseMultipleErrors'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized
          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: []
      x-codegen-request-body-name: contacts
  /customerbase/v1/contacts/import:
    post:
      tags:
      - CustomerBASE API
      summary: Import contacts from CSV
      description: Creates multiple contacts from CSV file upload
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              type: object
              properties:
                file:
                  type: string
                  description: 'CSV file with contact data (required headers: email,
                    linkedin_url)'
                  format: binary
        required: true
      responses:
        '201':
          description: All contacts imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.BulkResponse'
        '207':
          description: Contacts imported with some failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.BulkResponseMultipleErrors'
        '400':
          description: Invalid file format or data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '415':
          description: Unsupported content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
      security:
      - ApiKeyAutl: []
  /customerbase/v1/organizations:
    post:
      tags:
      - CustomerBASE API
      summary: Create a new organization
      description: Creates an organization if it doesn't exist based on website, custom
        ID, or LinkedIn URL. Returns existing organization if found.
      requestBody:
        description: Organization creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerbase.CreateOrganizationRequest'
        required: true
      responses:
        '201':
          description: Organization created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.OrganizationResponse'
        '206':
          description: Organization created with partial data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.OrganizationResponse'
        '400':
          description: Invalid request - Missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '409':
          description: Conflict - Organization already exists with provided identifiers
          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: []
      x-codegen-request-body-name: body
  /customerbase/v1/organizations/{id}:
    get:
      tags:
      - CustomerBASE API
      summary: Get organization details
      description: Retrieves detailed organization information by ID or COS ID
      parameters:
      - name: id
        in: path
        description: Organization ID or COS ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.OrganizationResponse'
        '206':
          description: Organization found with partial data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.OrganizationResponse'
        '400':
          description: Invalid organization ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '404':
          description: Organization 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: []
  /customerbase/v1/organizations/{id}/links/{externalSystem}/primary:
    put:
      tags:
      - CustomerBASE API
      summary: Set primary external system ID
      description: Sets or updates the primary external system identifier for an organization
      parameters:
      - name: id
        in: path
        description: Organization ID or COS ID
        required: true
        schema:
          type: string
      - name: externalSystem
        in: path
        description: External system name
        required: true
        schema:
          type: string
      requestBody:
        description: External system ID details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerbase.SetPrimaryExternalSystemIdRequest'
        required: true
      responses:
        '200':
          description: Primary ID set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerbase.ExternalSystemResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.BaseResponse'
        '404':
          description: Organization or external system 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: []
      x-codegen-request-body-name: body
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'
          examp

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customeros/refs/heads/main/openapi/customeros-customerbase-openapi.yml