openapi: 3.0.1
info:
  title: Spinwheel Embedded Debt Solutions Bank Accounts Users API
  description: Spinwheel's embedded credit and debt API. Connect a consumer, pull an Equifax-backed debt profile, refresh real-time liability balances and payoff quotes across credit cards and loans, originate bank-account-funded payments, and subscribe to webhook events. Most resources are scoped to a connected user identified by userId, the unique key used for accessing most Spinwheel APIs. Authentication uses a Spinwheel secret API key issued from the developer portal; the exact header scheme is gated behind the developer login and is not reconciled here - it is modeled as an HTTP bearer secret key.
  termsOfService: https://spinwheel.io/terms
  contact:
    name: Spinwheel Support
    url: https://docs.spinwheel.io
  version: '1.0'
servers:
- url: https://api.spinwheel.io
  description: Production
- url: https://sandbox-api.spinwheel.io
  description: Sandbox
- url: https://secure-api.spinwheel.io
  description: Production (secure)
- url: https://secure-sandbox-api.spinwheel.io
  description: Sandbox (secure)
security:
- bearerAuth: []
tags:
- name: Users
  description: Connect and manage users via SMS, KBA, phone, profile, or network token.
paths:
  /v1/users/{userId}:
    get:
      operationId: getUser
      tags:
      - Users
      summary: Retrieve a user
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User retrieved.
    delete:
      operationId: deleteUser
      tags:
      - Users
      summary: Delete a user
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: User deleted.
  /v1/users/connect/sms:
    post:
      operationId: connectUserSms
      tags:
      - Users
      summary: Connect a user via SMS
      description: Submits a US phone number and date of birth to send a one-time passcode by SMS.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                dateOfBirth:
                  type: string
                  format: date
      responses:
        '200':
          description: SMS connection initiated.
  /v1/users/connect/sms/verify:
    post:
      operationId: verifySmsConnection
      tags:
      - Users
      summary: Verify an SMS connection
      description: Verifies the one-time passcode delivered by SMS to complete the connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                code:
                  type: string
      responses:
        '200':
          description: SMS connection verified.
  /v1/users/connect/kba:
    post:
      operationId: connectUserKba
      tags:
      - Users
      summary: Connect a user via KBA
      description: Submits user PII to begin knowledge-based authentication.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: KBA questions returned.
  /v1/users/connect/kba/verify:
    post:
      operationId: verifyKbaAnswers
      tags:
      - Users
      summary: Submit answers for KBA
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: KBA answers verified.
  /v1/users/connect/phone:
    post:
      operationId: connectUserPhone
      tags:
      - Users
      summary: Connect a pre-verified (phone) user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: User connected.
  /v1/users/connect/network-token:
    post:
      operationId: connectUserNetworkToken
      tags:
      - Users
      summary: Connect a user via network token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: User connected.
components:
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: The unique key used for accessing most Spinwheel APIs.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Spinwheel secret API key issued from the developer portal (https://developer.spinwheel.io). The exact transport header is gated behind the developer login and not reconciled here.