openapi: 3.0.3
info:
  title: Pinwheel Accounts Sandbox API
  description: Pinwheel is the API for direct deposit switching, bill switching, and income & employment verification.
  version: v2025-07-08
  contact:
    name: Support
    email: support@getpinwheel.com
    url: https://getpinwheel.com
servers:
- url: https://api.getpinwheel.com/v1
  description: production
- url: https://sandbox.getpinwheel.com/v1
  description: sandbox
- url: https://development.getpinwheel.com/v1
  description: development
security:
- apiSecret: []
tags:
- name: Sandbox
paths:
  /sandbox/accounts/{account_id}:
    patch:
      tags:
      - Sandbox
      summary: Override an account's monitoring status
      description: Manually override a sandbox account's monitoring status.
      operationId: patch_monitoring_status_v1_sandbox_accounts__account_id__patch
      parameters:
      - description: UUID of the payroll account.
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the payroll account.
        name: account_id
        in: path
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayrollAccountPatchMonitoringStatus'
            examples:
              example:
                value:
                  monitoring_status: user_action_required
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PayrollAccountObjResponse'
                type: object
                required:
                - data
                x-tags:
                - Schemas
              examples:
                example:
                  value:
                    data:
                      id: eb240ec6-a227-47ca-b7c7-fbbdfe7170a0
                      created_at: '2021-01-06T15:59:13.530178+00:00'
                      link_token_id: bd2c09e7-1303-46d5-87c0-0ffa572d7ae4
                      platform_id: fce3eee0-285b-496f-9b36-30e976194736
                      connected: true
                      monitoring_status: active
                      data_updated_at:
                        direct_deposit_allocations: '2021-01-08T00:00:00.000000+00:00'
                      data_refreshed_at:
                        direct_deposit_allocations: '2021-01-09T00:00:00.000000+00:00'
                      end_user_id: my_user_12345
components:
  schemas:
    PayrollAccountDataRefreshed:
      properties:
        direct_deposit_allocations:
          type: string
          format: date-time
          title: direct_deposit_allocations
          description: ISO 8601 timestamp of the most recent check of direct deposit allocations data.
        income:
          type: string
          format: date-time
          title: income
          description: ISO 8601 timestamp of the most recent check of income data.
        employment:
          type: string
          format: date-time
          title: employment
          description: ISO 8601 timestamp of the most recent check of employment data.
        identity:
          type: string
          format: date-time
          title: identity
          description: ISO 8601 timestamp of the most recent check of identity data.
        shifts:
          type: string
          format: date-time
          title: shifts
          description: ISO 8601 timestamp of the most recent check of shifts data.
        paystubs:
          type: string
          format: date-time
          title: paystubs
          description: ISO 8601 timestamp of the most recent check of paystubs data.
      type: object
      title: PayrollAccountDataRefreshed
      x-tags:
      - Schemas
    PayrollAccountDataUpdated:
      properties:
        direct_deposit_allocations:
          type: string
          format: date-time
          title: direct_deposit_allocations
          description: ISO 8601 timestamp of when direct deposit allocations data most recently changed.
        income:
          type: string
          format: date-time
          title: income
          description: ISO 8601 timestamp of when income data most recently changed.
        employment:
          type: string
          format: date-time
          title: employment
          description: ISO 8601 timestamp of when employment data most recently changed.
        identity:
          type: string
          format: date-time
          title: identity
          description: ISO 8601 timestamp of when identity data most recently changed.
        shifts:
          type: string
          format: date-time
          title: shifts
          description: ISO 8601 timestamp of when shifts data most recently changed.
        paystubs:
          type: string
          format: date-time
          title: paystubs
          description: ISO 8601 timestamp of when paystubs data most recently changed.
      type: object
      title: PayrollAccountDataUpdated
      x-tags:
      - Schemas
    PayrollAccountObjResponse:
      properties:
        customer_id:
          type: string
          title: customer_id
          description: 'Banking platforms webhooks only: the customer ID associated with the platform''s customer.'
        tags:
          type: object
          title: tags
          description: The tags associated with the link token that triggered the job.
        reseller_customer_id:
          type: string
          title: reseller_customer_id
          description: The reseller customer ID associated with the job. Used exclusively for reseller customers.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: ISO 8601 timestamp of created time.
        link_token_id:
          type: string
          format: uuid
          title: link_token_id
          description: UUID of the link token used to create the account.
        platform_id:
          type: string
          format: uuid
          title: platform_id
          description: UUID of the platform associated with this account.
        connected:
          type: boolean
          title: connected
          description: If true, you can retrieve new data for the account using On Demand Updates or automatically via Monitoring.
        monitoring_status:
          allOf:
          - type: string
            enum:
            - active
            - degraded
            - user_action_required
            - customer_disabled
            - unavailable
          description: Monitoring status describes the the automated ability of Pinwheel to retrieve new account information.
        end_user_id:
          type: string
          title: end_user_id
          description: User ID provided by you, to associate Pinwheel users with your user model. Required if `account_id` is not provided. This ID will be returned in all webhook events and all account-affiliated API responses. Leading and trailing whitespace will be stripped. Do not include PII in this identifier.
        id:
          type: string
          format: uuid
          title: id
          description: Unique identifier for the object.
        data_updated_at:
          allOf:
          - $ref: '#/components/schemas/PayrollAccountDataUpdated'
          title: data_updated_at
          description: When data last changed for this payroll account.
        data_refreshed_at:
          allOf:
          - $ref: '#/components/schemas/PayrollAccountDataRefreshed'
          title: data_refreshed_at
          description: ISO 8601 timestamp of when data was last refreshed for this payroll account.
      type: object
      required:
      - created_at
      - platform_id
      - connected
      - monitoring_status
      - id
      - data_updated_at
      - data_refreshed_at
      title: Account
      x-tags:
      - Schemas
    PayrollAccountPatchMonitoringStatus:
      properties:
        monitoring_status:
          allOf:
          - type: string
            enum:
            - user_action_required
          description: Monitoring status describes the the automated ability of Pinwheel to retrieve new account information.
      type: object
      title: object
      x-tags:
      - Schemas
  securitySchemes:
    apiSecret:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: API Secret
    bearerAuth:
      description: Bearer token
      type: http
      scheme: bearer