Veritus Customers API

openapi: 3.1.0
info:
  title: Veritus Calls Customers API
  description: API for the Veritus Agent Platform
  license:
    name: MIT
  version: 1.0.0
servers:
- url: https://sandbox.veritus.com/api/v1
security:
- bearerAuth: []
tags:
- name: Customers
paths:
  /customers:
    post:
      description: 'Create a new customer. Once created, you can use the customer ID to enroll them into drip campaigns or make outbound calls. '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
        required: true
      responses:
        '200':
          description: Customer response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  externalId: CUST-12345
                  firstName: John
                  middleName: Christopher
                  lastName: Doe
                  email: john.doe@example.com
                  primaryPhone: '+12025551234'
                  secondaryPhone: '+12025555678'
                  address:
                    line1: 123 Main St
                    line2: Apt 4B
                    city: Washington
                    state: DC
                    zip: '20001'
                  collections:
                    principalBalance: 5000.0
                    originalCreditor: ABC Bank
                    accruedInterestAmount: 250.5
                    totalBalance: 5250.5
                    chargeOffDate: '2023-01-15'
                    firstDelinquencyDate: '2022-06-01'
                    settlementAggregationRate: 0.65
                    originalAccountNumber: '4111111111111111'
                    itemizationBalance: 5000.0
                    postItemizationInterest: 150.25
                    postItemizationFees: 100.25
                    postItemizationCredits: 50.0
                    postItemizationPayments: 200.0
                    productType: Credit Card
                    originalProductType: Visa Signature
                    extensions: null
                  ssnLastFour: '1234'
                  dateOfBirth: '1985-03-15'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '400':
          description: Bad request
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
        '409':
          description: Customer already exists
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: A customer with external ID 'abc1234' already exists.
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/bulk:
    post:
      description: Create multiple customers in a single request. Returns partial success - some customers may be created while others fail validation or already exist.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateCustomersRequest'
        required: true
      responses:
        '200':
          description: Bulk customer creation response. Contains arrays of successful and failed customer creations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateCustomersResponse'
              example:
                requestId: 838be160-334c-47aa-a559-d92d5cdc2ef4
                success: true
                data:
                  summary:
                    total: 2
                    succeeded: 1
                    failed: 1
                  results:
                  - externalId: CUST-123456
                    success: false
                    error: Customer with external ID 'CUST-123456' already exists
                  - success: true
                    customer:
                      id: 7ff34749-ddef-4a1f-8568-296a2240a6cc
                      externalId: CUST-987654
                      firstName: Johnny
                      middleName: Fuji
                      lastName: Appleseed
                      email: johnny@veritus.com
                      primaryPhone: '+14153334444'
                      secondaryPhone: null
                      ssnLastFour: '5345'
                      dateOfBirth: '1990-01-21'
                      address:
                        line1: 123 Main St
                        line2: Suite 200
                        city: San Francisco
                        state: CA
                        zip: '94131'
                      collections:
                        principalBalance: 5000
                        originalCreditor: ABC Bank
                        accruedInterestAmount: 250.5
                        totalBalance: 5250.5
                        chargeOffDate: '2023-01-15'
                        firstDelinquencyDate: '2022-06-01'
                        extensions: null
                      createdAt: '2025-10-23T05:38:45.468Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '400':
          description: Bad request
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}:
    patch:
      description: Update an existing customer's information. All fields are optional - only provide the fields you want to update.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer to update
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
        required: true
      responses:
        '200':
          description: Customer successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCustomerResponse'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  externalId: CUST-12345
                  firstName: Jane
                  middleName: Marie
                  lastName: Doe
                  email: jane.doe@example.com
                  primaryPhone: '+12025551234'
                  secondaryPhone: '+12025555678'
                  address:
                    line1: 456 Oak Ave
                    line2: Unit 12
                    city: Washington
                    state: DC
                    zip: '20001'
                  collections:
                    principalBalance: 4500.0
                    originalCreditor: ABC Bank
                    accruedInterestAmount: 250.5
                    totalBalance: 4750.5
                    chargeOffDate: '2023-01-15'
                    firstDelinquencyDate: '2022-06-01'
                    settlementAggregationRate: 0.65
                    originalAccountNumber: '4111111111111111'
                    itemizationBalance: 4500.0
                    postItemizationInterest: 150.25
                    postItemizationFees: 100.25
                    postItemizationCredits: 50.0
                    postItemizationPayments: 200.0
                    productType: Credit Card
                    originalProductType: Visa Signature
                    extensions: null
                  ssnLastFour: '1234'
                  dateOfBirth: '1985-03-15'
        '400':
          description: Bad request - invalid data provided
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Invalid request data
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/drip-campaigns:
    post:
      description: Enrolls a customer into a drip campaign. The customer is run through a compliance engine first. If compliance checks pass, the drip campaign is started immediately or scheduled for the next compliant time.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomersDripCampaignsPostRequest'
      tags:
      - Customers
  /customers/{customerId}/calls:
    post:
      description: Creates an outbound voice call to a customer. The customer is run through a compliance engine first. If compliance checks pass, the call is initiated. If the checks fail, the request will return an error with the specific compliance failure reasons.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
        required: true
      responses:
        '200':
          description: Create call response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCallResponse'
              example:
                requestId: 25deb7a2-ea2a-4993-8ad5-faed5367915b
                success: true
                data:
                  id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                  threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  toPhoneNumber: '+14155551234'
                  fromPhoneNumber: '+14155559876'
                  compliance:
                    passed: true
                    checksPassed:
                    - id: is-active
                      name: Is Active
                      description: Check if customer is active
                      reason: Customer is active
                    - id: cease-and-desist-exclusion
                      name: Cease and Desist Exclusion
                      description: Prevent calling customers who have requested cease and desist
                      reason: Customer has not requested cease and desist
                    - id: four-voice-call-per-day
                      name: Four Voice Call Per Day
                      description: Check if customer has had four or fewer voice calls today within the current respectful hours window
                      reason: Customer has had 3 voice calls today within respectful hours window (America/Los_Angeles), within the limit of 4
                    checksFailed: []
        '400':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 25deb7a2-ea2a-4993-8ad5-faed5367915b
                success: false
        '422':
          description: Unprocessable entity
          content:
            application/json:
              example:
                requestId: 25deb7a2-ea2a-4993-8ad5-faed5367915b
                publicFacingMessage: 'Customer not eligible for call. Failed rules: Respectful Hours Check (Customer local time is 03:00 (outside respectful hours 8am-8:50pm)), Model Validation Notice Delivered (No Model Validation Notice has been sent)'
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 25deb7a2-ea2a-4993-8ad5-faed5367915b
                success: false
      tags:
      - Customers
  /customers/{customerId}/drip-campaigns/{dripCampaignId}:
    delete:
      description: Cancel a drip campaign.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reason:
                  description: The reason the drip campaign was canceled.
                  type: string
                  enum:
                  - customer-converted
                  - customer-engaged
      responses:
        '200':
          description: Drip campaign canceled
          content: {}
      tags:
      - Customers
  /customers/{customerId}/interactions/sms/import:
    post:
      description: Import a single SMS interaction for a customer. Use this to sync historical SMS messages or record SMS conversations from external systems.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsImportRequest'
        required: true
      responses:
        '200':
          description: SMS interaction successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsImportResponse'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  channel: sms
                  direction: inbound
                  customerId: 7ff34749-ddef-4a1f-8568-296a2240a6cc
                  timestamp: '2024-01-15T10:30:00.000Z'
                  createdAt: '2024-01-15T10:35:00.000Z'
        '400':
          description: Bad request - invalid data provided
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Invalid request data
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/interactions/sms/import/bulk:
    post:
      description: Import multiple SMS interactions for a customer in a single request. Returns partial success - some messages may be imported while others fail validation.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsImportBulkRequest'
        required: true
      responses:
        '200':
          description: Bulk SMS import response. Contains arrays of successful and failed imports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsImportBulkResponse'
              example:
                requestId: 838be160-334c-47aa-a559-d92d5cdc2ef4
                success: true
                data:
                  summary:
                    total: 2
                    succeeded: 1
                    failed: 1
                  results:
                  - success: true
                    interaction:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      channel: sms
                      direction: inbound
                      customerId: 7ff34749-ddef-4a1f-8568-296a2240a6cc
                      timestamp: '2024-01-15T10:30:00.000Z'
                      createdAt: '2024-01-15T10:35:00.000Z'
                  - success: false
                    index: 1
                    error: Invalid phone number format
        '400':
          description: Bad request
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/interactions/sms/generate:
    post:
      description: Generate an AI-powered SMS response for a customer. The generated message can optionally be persisted as an outbound interaction.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsGenerateRequest'
        required: true
      responses:
        '200':
          description: SMS successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsGenerateResponse'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  message: Hi John, thank you for reaching out. I'd be happy to help you with your account. Could you please confirm the best time to discuss your payment options?
                  threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        '400':
          description: Bad request - invalid data provided
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Invalid request data
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '422':
          description: Unprocessable entity - validation failed
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: The 'to' field is required when persist is true
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/interactions/email/generate:
    post:
      description: Generate an AI-powered email response for a customer. The generated email can optionally be persisted as an outbound interaction.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailGenerateRequest'
        required: true
      responses:
        '200':
          description: Email successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailGenerateResponse'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  htmlBody: <p>Dear John,</p><p>Thank you for reaching out. I'd be happy to help you with your account. Could you please confirm the best time to discuss your payment options?</p><p>Best regards,<br>Sarah Mitchell</p>
                  plainTextBody: 'Dear John,


                    Thank you for reaching out. I''d be happy to help you with your account. Could you please confirm the best time to discuss your payment options?


                    Best regards,

                    Sarah Mitchell'
                  threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        '400':
          description: Bad request - invalid data provided
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Invalid request data
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/interactions/email/import:
    post:
      description: Import a single email interaction for a customer. Use this to sync historical emails or record email conversations from external systems.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailImportRequest'
        required: true
      responses:
        '200':
          description: Email interaction successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailImportResponse'
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  messageId: abc123@mail.example.com
                  threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  channel: email
                  direction: inbound
                  customerId: 7ff34749-ddef-4a1f-8568-296a2240a6cc
                  timestamp: '2024-01-15T10:30:00.000Z'
                  createdAt: '2024-01-15T10:35:00.000Z'
        '400':
          description: Bad request - invalid data provided
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Invalid request data
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
  /customers/{customerId}/interactions/email/import/bulk:
    post:
      description: Import multiple email interactions for a customer in a single request. Returns partial success - some emails may be imported while others fail validation.
      parameters:
      - name: customerId
        in: path
        description: The unique identifier of the customer
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailImportBulkRequest'
        required: true
      responses:
        '200':
          description: Bulk email import response. Contains arrays of successful and failed imports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailImportBulkResponse'
              example:
                requestId: 838be160-334c-47aa-a559-d92d5cdc2ef4
                success: true
                data:
                  summary:
                    total: 2
                    succeeded: 1
                    failed: 1
                  results:
                  - success: true
                    interaction:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      messageId: abc123@mail.example.com
                      threadId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      channel: email
                      direction: inbound
                      customerId: 7ff34749-ddef-4a1f-8568-296a2240a6cc
                      timestamp: '2024-01-15T10:30:00.000Z'
                      createdAt: '2024-01-15T10:35:00.000Z'
                  - success: false
                    index: 1
                    error: Email body is required
        '400':
          description: Bad request
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Unauthorized. Make sure to pass the correct authorization token.
                success: false
        '404':
          description: Customer not found
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                publicFacingMessage: Customer not found
                success: false
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                requestId: 96b887fb-9371-4515-b51e-28434f58dd7e
                success: false
      tags:
      - Customers
components:
  schemas:
    EmailImportRequest:
      required:
      - direction
      - timestamp
      - from
      - to
      - subject
      type: object
      properties:
        direction:
          description: The direction of the email.
          type: string
          enum:
          - inbound
          - outbound
        timestamp:
          description: When the email was sent or received. ISO-8601 format.
          type: string
          format: date-time
        from:
          description: The sender's email address.
          type: string
          format: email
        to:
          description: Array of recipient email addresses. Must contain at least 1 recipient.
          type: array
          items:
            type: string
            format: email
          minItems: 1
        cc:
          description: Array of CC recipient email addresses.
          type: array
          items:
            type: string
            format: email
          default: []
        bcc:
          description: Array of BCC recipient email addresses.
          type: array
          items:
            type: string
            format: email
          default: []
        subject:
          description: The email subject line.
          type: string
        plainTextBody:
          description: The plain text content of the email. At least one of plainTextBody or htmlBody must have non-empty content.
          type: string
        htmlBody:
          description: The HTML content of the email. At least one of plainTextBody or htmlBody must have non-empty content.
          type: string
        threadId:
          description: Optional thread identifier to group related emails together.
          type: string
        messageId:
          description: Optional message identifier from the email system.
          type: string
    UpdateCustomerRequest:
      type: object
      properties:
        firstName:
          description: The first name of the customer.
          type: string
        middleName:
          description: The middle name of the customer.
          type: string
        lastName:
          description: The last name of the customer.
          type: string
        email:
          description: The email address of the customer.
          type: string
        primaryPhone:
          description: The primary phone number of the customer. (E.164 format)
          type: string
        secondaryPhone:
          description: The secondary p

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