openapi: 3.0.3
info:
  title: Tratta Bulk Operations Customers API
  description: The Tratta REST API enables programmatic integration with Tratta's debt collection and payment experience platform. Manage debt accounts, payment plans, transactions, customers, charges, and webhooks for collections workflows. Supports both sandbox and production environments.
  version: v1.0.0
  contact:
    name: Tratta Support
    url: https://docs.tratta.io/
  x-logo:
    url: https://www.tratta.io/logo.png
servers:
- url: https://{org-uuid}.production.tratta.io/api/v1
  description: Tratta Production Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
- url: https://{org-uuid}.sandbox.tratta.io/api/v1
  description: Tratta Sandbox Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
security:
- BearerAuth: []
tags:
- name: Customers
  description: Customer account management
paths:
  /customers:
    get:
      operationId: listCustomers
      summary: List Customers
      description: Returns a paginated list of customers in the organization.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successful response with customer list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      summary: Create Customer
      description: Creates a new customer record.
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{id}:
    get:
      operationId: getCustomer
      summary: Get Customer
      description: Returns a single customer by ID.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/IdParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCustomer
      summary: Update Customer
      description: Updates an existing customer record.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
      description: Page number for pagination
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
      description: Number of records per page (1-500)
    IncludeParam:
      name: include
      in: query
      required: false
      schema:
        type: string
      description: Comma-delimited list of related resources to include in response (e.g., customers,payment_methods)
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource unique identifier
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        errorCode:
          type: string
          description: Optional error code
    Customer:
      type: object
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CustomerRequest:
      type: object
      required:
      - first_name
      - last_name
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        current_page:
          type: integer
        per_page:
          type: integer
        total_pages:
          type: integer
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
        last:
          type: string
    CustomerResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Customer'
    CustomerListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Unprocessable entity - missing parameters or invalid data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - valid data but request failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by Tratta after organization setup