customers.yaml

post:
  summary: Add a new customer
  description: >-
    Register a new customer in the system with an account identifier and bank account
    information
  operationId: createCustomer
  tags:
    - Customers
  security:
    - BasicAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: ../../components/schemas/customers/CustomerCreateRequestOneOf.yaml
        examples:
          individualCustomer:
            summary: Create an individual customer
            value:
              customerType: INDIVIDUAL
              platformCustomerId: ind-9f84e0c2
              fullName: Jane Smith
              birthDate: '1990-01-15'
              nationality: US
          businessCustomer:
            summary: Create a business customer
            value:
              customerType: BUSINESS
              platformCustomerId: biz-acme-001
              businessInfo:
                legalName: Acme Corporation
                doingBusinessAs: Acme
                country: US
                registrationNumber: '5523041'
                incorporatedOn: '2018-03-14'
                entityType: LLC
                taxId: 47-1234567
                countriesOfOperation:
                  - US
                businessType: FINANCE_AND_INSURANCE
                purposeOfAccount: Payout to contractors
                sourceOfFunds: Funds derived from customer payments for software services
                expectedMonthlyTransactionCount: 100_TO_500
                expectedMonthlyTransactionVolume: 100K_TO_1M
                expectedRecipientJurisdictions:
                  - US
                  - MX
              address:
                line1: 123 Market Street
                line2: Suite 400
                city: San Francisco
                state: CA
                postalCode: '94105'
                country: US
  responses:
    '201':
      description: Customer created successfully
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/customers/CustomerOneOf.yaml
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error400.yaml
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error401.yaml
    '409':
      description: Conflict - Customer with the UMA address already exists
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error409.yaml
    '500':
      description: Internal service error
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error500.yaml
    '501':
      description: Not implemented
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error501.yaml
get:
  summary: List customers
  description: >
    Retrieve a list of customers with optional filtering parameters. Returns all
    customers that match

    the specified filters. If no filters are provided, returns all customers
    (paginated).
  operationId: listCustomers
  tags:
    - Customers
  security:
    - BasicAuth: []
  parameters:
    - name: platformCustomerId
      in: query
      description: Filter by platform-specific customer identifier
      required: false
      schema:
        type: string
    - name: customerType
      in: query
      description: Filter by customer type
      required: false
      schema:
        $ref: ../../components/schemas/customers/CustomerType.yaml
    - name: createdAfter
      in: query
      description: Filter customers created after this timestamp (inclusive)
      required: false
      schema:
        type: string
        format: date-time
    - name: createdBefore
      in: query
      description: Filter customers created before this timestamp (inclusive)
      required: false
      schema:
        type: string
        format: date-time
    - name: updatedAfter
      in: query
      description: Filter customers updated after this timestamp (inclusive)
      required: false
      schema:
        type: string
        format: date-time
    - name: updatedBefore
      in: query
      description: Filter customers updated before this timestamp (inclusive)
      required: false
      schema:
        type: string
        format: date-time
    - name: limit
      in: query
      description: Maximum number of results to return (default 20, max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    - name: cursor
      in: query
      description: Cursor for pagination (returned from previous request)
      required: false
      schema:
        type: string
    - name: umaAddress
      in: query
      description: Filter by uma address
      required: false
      schema:
        type: string
    - name: isIncludingDeleted
      in: query
      description: Whether to include deleted customers in the results. Default is false.
      required: false
      schema:
        type: boolean
  responses:
    '200':
      description: Successful operation
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - hasMore
            properties:
              data:
                type: array
                description: List of customers matching the filter criteria
                items:
                  $ref: ../../components/schemas/customers/CustomerOneOf.yaml
              hasMore:
                type: boolean
                description: Indicates if more results are available beyond this page
              nextCursor:
                type: string
                description: >-
                  Cursor to retrieve the next page of results (only present if
                  hasMore is true)
              totalCount:
                type: integer
                description: >-
                  Total number of customers matching the criteria (excluding
                  pagination)
    '400':
      description: Bad request - Invalid parameters
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error400.yaml
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error401.yaml
    '500':
      description: Internal service error
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error500.yaml