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

# Add recipients

> Creates one or more recipients. Each recipient receives an onboarding URL they can use to complete their profile and (optionally) tax information.



## OpenAPI

````yaml /api-reference/openapi.json post /recipients
openapi: 3.1.0
info:
  title: Karat Payout API
  description: >-
    Your gateway to seamless, automated, and scalable payment solutions. The
    Karat Payout API lets you create recipients, send payouts, track payment
    status, manage tax documents, record external payments, and subscribe to
    webhook events.
  version: 1.0.0
servers:
  - url: https://payouts.api.trykarat.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Create and manage outgoing payouts to recipients.
  - name: Recipients
    description: Manage the payees you send payouts to.
  - name: Tax
    description: Retrieve recipient tax forms (W-9) and download links.
  - name: External Payments
    description: Record and manage payments made outside of Karat.
  - name: Webhooks
    description: Subscribe to event notifications for payout activity.
paths:
  /recipients:
    post:
      tags:
        - Recipients
      summary: Add recipients
      description: >-
        Creates one or more recipients. Each recipient receives an onboarding
        URL they can use to complete their profile and (optionally) tax
        information.
      operationId: createRecipients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientsRequest'
            example:
              recipients:
                - firstName: Jordan
                  lastName: Lee
                  email: jordan@example.com
                  nickname: Jordan (design)
                  shouldCollectTaxInfo: true
      responses:
        '201':
          description: The recipients were created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                      recipients:
                        type: array
                        items:
                          $ref: '#/components/schemas/Recipient'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateRecipientsRequest:
      type: object
      required:
        - recipients
      properties:
        recipients:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RecipientInput'
    Recipient:
      type: object
      properties:
        id:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        nickname:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        onboardingUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            URL the recipient can use to complete onboarding, or null if already
            onboarded.
        status:
          $ref: '#/components/schemas/RecipientStatus'
    RecipientInput:
      type: object
      required:
        - firstName
        - lastName
        - email
      properties:
        firstName:
          type: string
          minLength: 1
        lastName:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        nickname:
          type: string
        shouldCollectTaxInfo:
          type: boolean
          description: >-
            Whether to require this recipient to complete tax information.
            Defaults to true.
    RecipientStatus:
      type: string
      description: Lifecycle status of a recipient.
      enum:
        - created
        - active
        - missing_tax_form
        - pending_review
        - approved_w9
        - approved_w8
        - approved_1099_exempt
        - approved_no_tax_collection
    Error:
      type: object
      description: Standard error envelope returned for all non-2xx responses.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
          required:
            - message
      required:
        - error
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'amount: amount must be positive'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Invalid api key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as a bearer token: `Authorization: Bearer <API_KEY>`.'

````