> ## Documentation Index
> Fetch the complete documentation index at: https://dotsdev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Payout Request

> Submit a payout request from a person when you know their phone number or user id. Once the payout request is approved, they will be sent a Payout Link to onboard and recieve funds.



## OpenAPI

````yaml /v2.yaml post /v2/payout-requests
openapi: 3.1.0
info:
  title: dots api
  version: '1.0'
  summary: Dots Payout API
  description: Scalable and Flexible Payouts Infrastructure
  contact:
    name: Kartikye Mittal
    url: https://dots.dev
    email: info@dots.dev
  license:
    name: MIT
    url: https://opensource.org/license/mit/
servers:
  - url: https://api.dots.dev/api
    description: Production
security:
  - api_key: []
tags:
  - name: accounts-payable
    description: Accounts Payable Routes
  - name: apps
    description: App Routes
  - name: flows
    description: Flow routes
  - name: organizations
    description: Organization Routes
  - name: payment-customers
    description: Payment Customer Routes
  - name: payments
    description: Payment Routes
  - name: payout-batches
    description: Payout Batch Routes
  - name: payout-links
    description: Payout Link Routes
  - name: payout-requests
    description: Payout Request Routes
  - name: payouts
    description: Payout Routes
  - name: transactions
    description: Transaction Routes
  - name: transfer-batches
    description: Transfer Batch routes
  - name: transfers
    description: Transfer routes
  - name: users
    description: User routes
paths:
  /v2/payout-requests:
    parameters: []
    post:
      tags:
        - payout-requests
      summary: Create a Payout Request
      description: >-
        Submit a payout request from a person when you know their phone number
        or user id. Once the payout request is approved, they will be sent a
        Payout Link to onboard and recieve funds.
      operationId: create-payouts-request
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                amount:
                  type: integer
                  description: The amount in cents to pay the user.
                  exclusiveMinimum: 0
                user_id:
                  type: string
                  format: uuid
                  description: The user's id. `user_id` or `payee` is required.
                payee:
                  type: object
                  description: The payee's phone number. `user_id` or `payee` is required.
                  properties:
                    country_code:
                      type: string
                      description: >-
                        Country code of the payee's phone number e.g. "1" for
                        USA.
                    phone_number:
                      type: string
                      description: Rest of the payee's phone number.
                  required:
                    - country_code
                    - phone_number
                metadata:
                  description: >-
                    Set of key-value pairs that you can attach to an object.
                    This can be useful for storing additional information about
                    the object in a structured format.
                  type:
                    - string
                    - object
                memo:
                  type: string
                  description: Add a memo to payout request
              required:
                - amount
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout-request'
                description: The `payout-request` id.
components:
  schemas:
    payout-request:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the `payout-request`.
        created:
          type: string
          format: date-time
          description: Date that the `payout-request` was created.
        amount:
          type: number
          description: Amount in cents of the `payout-request`.
        status:
          type: string
          enum:
            - created
            - approved
            - rejected
          description: Status of the `payout-request`.
        payee:
          type: object
          properties:
            country_code:
              type: string
            phone_number:
              type: string
        payout-link:
          $ref: '#/components/schemas/payout-link'
          description: >-
            The `payout-link` that was sent when the `payout-request` was
            approved. 
        user:
          $ref: '#/components/schemas/user'
          description: The `user` that requested the payout.
        metadata:
          type:
            - string
            - object
            - 'null'
          description: >-
            Set of key-value pairs that you can attach to an object. This can be
            useful for storing additional information about the object in a
            structured format.
        memo:
          type:
            - string
    payout-link:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the `payout-link`.
        created:
          type: string
          format: date-time
          description: Date the `payout-link` was created.
        link:
          type: string
          format: uri
          description: URL to access the `payout-link`.
        amount:
          type: number
          description: The amount to pay in cents.
        status:
          type: string
          enum:
            - created
            - delivery_pending
            - delivery_failed
            - sent
            - delivered
            - claimed
            - reversed
            - canceled
            - expired
            - failed
          description: Status of the `payout-link`.
        payee:
          type: object
          description: Information about the payee. It is used to pre-fill information.
          properties:
            first_name:
              type: string
              description: Payee's first name.
            last_name:
              type: string
              description: Payee's last name.
            email:
              type: string
              format: email
              description: Payee's email address.
            country_code:
              type: string
              description: Country code of the payee's phone number e.g. "1" for USA.
            phone_number:
              type: string
              description: Rest of the payee's phone number.
        delivery:
          type: object
          properties:
            method:
              type: string
              enum:
                - link
                - sms
                - email
            email:
              type: string
              format: email
            country_code:
              type: string
            phone_number:
              type: string
        tax_exempt:
          type: boolean
          description: >-
            Transfers marked as `tax_exempt` will not be counted towards the
            1099 threshold.
        claimed_user_id:
          type: string
          format: uuid
          description: ID of the `user` that has claimed the `payout-link`.
        flow_id:
          type: string
          format: uuid
          description: ID of the payout flow UI that is sent to the user.
        transfer_id:
          type: string
          format: uuid
          description: ID of the `transfer` created for this `payout-link`.
        memo:
          type:
            - string
            - 'null'
          description: Optional memo added to this `payout-link`
        metadata:
          type:
            - string
            - object
            - 'null'
          description: >-
            Set of key-value pairs that you can attach to an object. This can be
            useful for storing additional information about the object in a
            structured format.
    user:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: object
          properties:
            country_code:
              type: string
            phone_number:
              type: string
        default_payout_method:
          $ref: '#/components/schemas/rail'
        default_payout_method_details:
          $ref: '#/components/schemas/payment-method'
        wallet:
          $ref: '#/components/schemas/wallet'
        status:
          type: string
          enum:
            - verified
            - unverified
            - disabled
            - in_review
        compliance:
          type: object
          properties:
            tax_id_collected:
              type: boolean
              description: Deprecated. Use `w9.tax_id_collected` instead.
              depcrecated: true
            tax_id_verification:
              type: string
              enum:
                - unsubmitted
                - pending
                - matched
                - mismatched
              description: >-
                Tax ID verification status. A mismatched tax ID may be corrected
                and resubmitted.
            address_collected:
              type: boolean
              description: Deprecated. Use `w9.address_collected` instead.
              deprecated: true
            date_of_birth_collected:
              type: boolean
              description: The user's date of birth was collected.
            must_collect_1099:
              type: boolean
              description: >-
                The user's 1099 information needs to be collected to resume
                payouts.
            1099_collected:
              type: boolean
              description: The user's 1099 information was collected.
            w8_ben_collected:
              type: boolean
              description: The user's W8-BEN information was collected.
            flagged:
              type: boolean
              description: >-
                The user is flagged for review. For more information, see the
                `flags` object.
            id_verified:
              type: boolean
              description: The user's id was verified.
            has_criminal_activity:
              type: boolean
              description: The user has criminal activity based on a background check.
            background_check:
              type: object
              description: >-
                Background check result. Only returned when a background check
                exists for the user.
              properties:
                status:
                  type: string
                  enum:
                    - not_started
                    - started
                    - pending
                    - consider
                    - pass
                    - failed
                    - canceled
                    - expired
                    - information_mismatch
                updated:
                  type: string
                  format: date-time
                  description: The time the background check was last updated.
            w9:
              type:
                - object
                - null
              description: >-
                Information about the user's W9 form. null if the user is not a
                US individual or business.
              properties:
                entity_type:
                  type: string
                  enum:
                    - individual
                    - business
                business_name:
                  type:
                    - string
                    - null
                tax_id_collected:
                  type: boolean
                address_collected:
                  type: boolean
            flags:
              type: object
              properties:
                ofac:
                  type: boolean
                  description: >-
                    True when the user is flagged for potential OFAC compliance
                    issues.
                ofac_status:
                  type: string
                  enum:
                    - unflagged
                    - id_verification_required
                    - in_review
                    - flagged
                  description: Status of the user's OFAC compliance verification.
                payout_method:
                  type: boolean
                  description: True when two or more users share the same payout method.
                payout_method_cycle:
                  type: boolean
                  description: >-
                    True when the user has connected or disconnected payout
                    methods repeatedly over a short period of time.
                name_mismatch:
                  type: boolean
                  description: >-
                    True when the user's name does not match a name submitted
                    during IDV or through a payout method.
        metadata:
          type:
            - string
            - object
            - 'null'
          description: >-
            Set of key-value pairs that you can attach to an object. This can be
            useful for storing additional information about the object in a
            structured format.
        payout_options_exclude_list:
          type: array
          items:
            $ref: '#/components/schemas/rail'
          description: >-
            Payout rails hidden from this user. Stacks with app-level
            exclusions.
        1099_adjustment:
          $ref: '#/components/schemas/1099-adjustment'
          description: >-
            Current-year 1099 adjustment for the user, if one has been set. Only
            returned by the retrieve-a-user endpoint (`GET /v2/users/{user_id}`)
            when the application's configured filing type has a matching
            adjustment; omitted otherwise and never included in list responses.
    rail:
      type: string
      enum:
        - ach
        - paypal
        - venmo
        - cash_app
        - intl_bank
        - airtm
        - payoneer
        - crypto
    payment-method:
      type: object
      properties:
        id:
          type: string
          description: ID of the `payment-method`.
        platform:
          enum:
            - ach
            - paypal
            - venmo
            - cash_app
            - intl_transfer
            - airtm
            - payoneer
          type: string
        description:
          type: string
        mask:
          type: string
        email:
          type: string
        phone_number:
          type: string
        cash_tag:
          type: string
        country:
          type: string
          format: iso3166
        currency:
          type: string
          format: iso4217
        rtp_enabled:
          type: boolean
          description: >-
            Indicates if RTP is enabled for the payment method (applies to ach
            only).
        meta:
          description: >-
            Optional metadata for the payout method. Can be any valid JSON value
            (object, string, number, boolean, array, or null).
      required:
        - platform
    wallet:
      type: object
      properties:
        amount:
          type: integer
        withdrawable_amount:
          type: integer
        credit_balance:
          type: integer
    1099-adjustment:
      description: >-
        Income paid outside of the Dots platform in the current calendar year.
        The form must match the application's configured 1099 filing type.
      oneOf:
        - title: 1099-NEC adjustment
          type: object
          additionalProperties: false
          properties:
            year:
              type: integer
              description: The current calendar year.
            form:
              type: string
              const: 1099-NEC
            amount:
              type: integer
              minimum: 1
              description: The adjustment amount in cents.
          required:
            - year
            - form
            - amount
        - title: 1099-K adjustment
          type: object
          additionalProperties: false
          properties:
            year:
              type: integer
              description: The current calendar year.
            form:
              type: string
              const: 1099-K
            monthly_amounts:
              type: object
              additionalProperties: false
              description: Adjustment amounts in cents for every month of the year.
              properties:
                january:
                  type: integer
                february:
                  type: integer
                march:
                  type: integer
                april:
                  type: integer
                may:
                  type: integer
                june:
                  type: integer
                july:
                  type: integer
                august:
                  type: integer
                september:
                  type: integer
                october:
                  type: integer
                november:
                  type: integer
                december:
                  type: integer
              required:
                - january
                - february
                - march
                - april
                - may
                - june
                - july
                - august
                - september
                - october
                - november
                - december
            transaction_count:
              type: integer
              minimum: 1
              description: Transactions paid outside of Dots during the year.
          required:
            - year
            - form
            - monthly_amounts
  securitySchemes:
    api_key:
      type: http
      scheme: basic

````