CustomerOS CustomerBASE API

openapi: 3.2.0
info:
  description: CustomerOS API for multiple services (Verify, Enrich, Orgs)
  title: CustomerOS CustomerBASE API
  contact: {}
  version: '1.0'
servers:
- url: https://api.customeros.ai/
tags:
- name: CustomerBASE API
paths:
  /customerbase/v1/contacts:
    post:
      security:
      - ApiKeyAuth: []
      description: Creates a contact from either JSON or CSV upload
      tags:
      - CustomerBASE API
      summary: Create a new contact
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerbase.ContactRecord'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/customerbase.ContactRecord'
        description: Contact information
      operationId: postCustomerbaseV1Contacts
      x-operation-id-source: derived
  /customerbase/v1/contacts/bulk:
    post:
      security:
      - ApiKeyAuth: []
      description: Creates multiple contacts from JSON input
      tags:
      - CustomerBASE API
      summary: Create multiple contacts
      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'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/customerbase.ContactRecord'
        description: Array of contacts to create
        required: true
      operationId: postCustomerbaseV1ContactsBulk
      x-operation-id-source: derived
  /customerbase/v1/contacts/import:
    post:
      security:
      - ApiKeyAutl: []
      description: Creates multiple contacts from CSV file upload
      tags:
      - CustomerBASE API
      summary: Import contacts from CSV
      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'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: 'CSV file with contact data (required headers: email, linkedin_url)'
                  format: binary
              required:
              - file
      operationId: postCustomerbaseV1ContactsImport
      x-operation-id-source: derived
  /customerbase/v1/organizations:
    post:
      security:
      - ApiKeyAuth: []
      description: Creates an organization if it doesn't exist based on website, custom ID, or LinkedIn URL. Returns existing organization if found.
      tags:
      - CustomerBASE API
      summary: Create a new organization
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerbase.CreateOrganizationRequest'
        description: Organization creation request
        required: true
      operationId: postCustomerbaseV1Organizations
      x-operation-id-source: derived
  /customerbase/v1/organizations/{id}:
    get:
      security:
      - ApiKeyAuth: []
      description: Retrieves detailed organization information by ID or COS ID
      tags:
      - CustomerBASE API
      summary: Get organization details
      parameters:
      - example: org_123
        description: Organization ID or COS ID
        name: id
        in: path
        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'
      operationId: getCustomerbaseV1OrganizationsById
      x-operation-id-source: derived
  /customerbase/v1/organizations/{id}/links/{externalSystem}/primary:
    put:
      security:
      - ApiKeyAuth: []
      description: Sets or updates the primary external system identifier for an organization
      tags:
      - CustomerBASE API
      summary: Set primary external system ID
      parameters:
      - example: org_123
        description: Organization ID or COS ID
        name: id
        in: path
        required: true
        schema:
          type: string
      - example: salesforce
        description: External system name
        name: externalSystem
        in: path
        required: true
        schema:
          type: string
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerbase.SetPrimaryExternalSystemIdRequest'
        description: External system ID details
        required: true
      operationId: putCustomerbaseV1OrganizationsByIdLinksByExternalSystemPrimary
      x-operation-id-source: derived
components:
  schemas:
    customerbase.ExternalSystemRecord:
      description: External system information and its relationship to an organization
      type: object
      properties:
        externalId:
          description: 'External system identifier

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

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

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

            example: true'
          type: boolean
    customerbase.OrganizationResponse:
      description: Response structure for single organization operations
      type: object
      properties:
        organization:
          description: The organization information
          allOf:
          - $ref: '#/components/schemas/customerbase.OrganizationRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
    customerbase.BulkSummary:
      description: Summary statistics for bulk operations
      type: object
      properties:
        failed:
          description: 'Number of failed records

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

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

            example: 100'
          type: integer
    customerbase.ExternalLink:
      description: External system link information
      type: object
      properties:
        id:
          description: 'External system identifier

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

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

            example: true'
          type: boolean
    rest.BaseResponse:
      description: Standard response structure for API operations
      type: object
      properties:
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
    customerbase.BulkResponseMultipleErrors:
      description: Response structure for bulk operations with multiple error details
      type: object
      properties:
        details:
          description: List of error details
          type: array
          items:
            $ref: '#/components/schemas/customerbase.BulkErrorDetails'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
        summary:
          description: Summary of the bulk operation
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkSummary'
    customerbase.OrganizationRecord:
      description: Detailed organization information returned by API operations
      type: object
      properties:
        cosId:
          description: 'CustomerOS unique identifier

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

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

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

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

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

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

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

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

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

            example: https://customeros.ai'
          type: string
    customerbase.CreateOrganizationRequest:
      description: Request to create an organization
      type: object
      properties:
        customId:
          description: 'Custom ID provided by the user

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

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

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

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

            required: true

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

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

            example: https://customeros.ai'
          type: string
    customerbase.SetPrimaryExternalSystemIdRequest:
      description: Request to set or replace the primary external system ID
      type: object
      properties:
        externalId:
          description: 'The ID of the external system to be set as primary

            required: true

            example: stripe-1234'
          type: string
    customerbase.BulkErrorDetails:
      description: Error details for failed operations in bulk processing
      type: object
      properties:
        description:
          description: 'Description of the error

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

            example: invalid@email..com'
          type: string
    customerbase.ContactsResponse:
      description: Response structure for multiple contact operations
      type: object
      properties:
        contacts:
          description: List of contacts
          type: array
          items:
            $ref: '#/components/schemas/customerbase.ContactRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
    customerbase.SingleContactResponse:
      description: Response structure for single contact operations
      type: object
      properties:
        contact:
          description: The contact information
          allOf:
          - $ref: '#/components/schemas/customerbase.ContactRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
    customerbase.ExternalSystemResponse:
      description: Response structure for external system operations
      type: object
      properties:
        organization:
          description: The external system information
          allOf:
          - $ref: '#/components/schemas/customerbase.ExternalSystemRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
    customerbase.ContactRecord:
      description: Request to create a contact
      type: object
      properties:
        contactId:
          description: 'Contact''s unique identifier

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

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

            example: https://linkedin.com/in/john-doe'
          type: string
    customerbase.BulkResponse:
      description: Response structure for bulk operations with single error detail
      type: object
      properties:
        details:
          description: Error details if any
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkErrorDetails'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          description: Status indicates the result of the operation ("success" or "error")
          type: string
          example: success
        summary:
          description: Summary of the bulk operation
          allOf:
          - $ref: '#/components/schemas/customerbase.BulkSummary'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-CUSTOMER-OS-API-KEY
      in: header