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

# Create Payee

> Add a payee — a person or business that one of your users wants to send money to. Once the payee is added, you can give them one or more payout destinations (the actual accounts where the money is delivered).



## OpenAPI

````yaml POST /v1/platform/payees
openapi: 3.1.0
info:
  title: Finogate Platform API v1
  version: 0.1.0
servers:
  - url: https://api-sandbox.finogates.com
    description: Sandbox
  - url: https://api.finogates.com
    description: Production
security: []
tags:
  - name: auth
  - name: users
  - name: payees
  - name: verification
  - name: bank accounts
  - name: card processing
  - name: digital-assets
  - name: international
  - name: fees
  - name: onboarding
  - name: pending-applications
  - name: wallets
  - name: payments
  - name: document mailing
  - name: merchant onboarding
  - name: catalog
  - name: webhooks
  - name: screening
  - name: Platform - File Scanning
  - name: phone-numbers
  - name: sms
  - name: calls
  - name: listings
  - name: Card Transfers
  - name: embed-tokens
paths:
  /v1/platform/payees:
    post:
      tags:
        - payees
      summary: Add a Payee
      description: >-
        Add a payee — a person or business that one of your users wants to send
        money to. Once the payee is added, you can give them one or more payout
        destinations (the actual accounts where the money is delivered).
      operationId: create_payee_v1_platform_payees_post
      parameters:
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
            description: The unique ID of the user who owns this payee.
            examples:
              - b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4
            title: User Id
          description: The unique ID of the user who owns this payee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeCreate'
      responses:
        '200':
          description: The newly created payee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_PayeeRead_'
              example:
                status_code: 201
                data:
                  id: d4e5f6a7-b8c9-0123-4567-890abcdef012
                  display_name: Acme Supplier
                  first_name: Acme
                  last_name: Supplier
                  is_business: false
                  email: payments@acme-supplier.com
                  phone: '+14155550123'
                  status: active
                  is_active: true
                  owner_user_id: b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4
                  created_at: '2025-06-10T18:10:42.000Z'
                  updated_at: '2025-06-10T18:10:42.000Z'
                query_generated_time: 1712847600000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    PayeeCreate:
      properties:
        first_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: First Name
        middle_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Middle Name
        last_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Last Name
        maiden_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Maiden Name
        date_of_birth:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Date Of Birth
        nationality:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Nationality
        gender:
          anyOf:
            - type: string
              maxLength: 1
            - type: 'null'
          title: Gender
        doc_number:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Doc Number
        doc_type:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Doc Type
        doc_issue_country:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Doc Issue Country
        doc_issue_date:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Doc Issue Date
        doc_due_date:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Doc Due Date
        doc_issuer:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Doc Issuer
        state:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: State
        city:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: City
        street:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Street
        postal_code:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Postal Code
          description: >-
            Recipient's ZIP / postal code. Required by some payout corridors
            (e.g. US) — the payout is rejected without it.
        is_business:
          type: boolean
          title: Is Business
          description: >-
            Set to true when this payee is a business/organization rather than
            an individual. When true, send business_name; first/last name are
            optional (used for international/UniTeller payouts). This is fixed
            at creation and cannot be changed later.
          default: false
        business_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Business Name
          description: >-
            Organization name. Required when is_business is true; leave empty
            for an individual.
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          title: Phone
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      title: PayeeCreate
      description: Request body for POST /tenant/payees.
      example:
        email: payments@acme-supplier.com
        first_name: Acme
        is_business: false
        last_name: Supplier
        phone: '+14155550123'
    CommonResponse_PayeeRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/PayeeRead'
          description: Payload or error details.
        query_generated_time:
          type: integer
          title: Query Generated Time
          description: >-
            UTC timestamp (milliseconds since epoch) when response was
            generated.
      type: object
      required:
        - status_code
        - data
        - query_generated_time
      title: CommonResponse[PayeeRead]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PayeeRead:
      properties:
        first_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: First Name
        middle_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Middle Name
        last_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Last Name
        maiden_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Maiden Name
        date_of_birth:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Date Of Birth
        nationality:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Nationality
        gender:
          anyOf:
            - type: string
              maxLength: 1
            - type: 'null'
          title: Gender
        doc_number:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Doc Number
        doc_type:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Doc Type
        doc_issue_country:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Doc Issue Country
        doc_issue_date:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Doc Issue Date
        doc_due_date:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Doc Due Date
        doc_issuer:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Doc Issuer
        state:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: State
        city:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: City
        street:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Street
        postal_code:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Postal Code
          description: >-
            Recipient's ZIP / postal code. Required by some payout corridors
            (e.g. US) — the payout is rejected without it.
        id:
          type: string
          format: uuid
          title: Id
        display_name:
          type: string
          title: Display Name
        is_business:
          type: boolean
          title: Is Business
          default: false
        business_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Name
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        status:
          type: string
          title: Status
        is_active:
          type: boolean
          title: Is Active
        owner_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Owner User Id
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
      type: object
      required:
        - id
        - display_name
        - status
        - is_active
      title: PayeeRead
      description: Payee representation returned by the API.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````