---
title: "Add recipients"
method: POST
path: "/recipients"
tags: ["Recipients"]
---

# Add recipients

`POST /recipients`

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

## Request body

- CreateRecipientsRequest
  - `recipients` RecipientInput[], required
    - `firstName` string, required
    - `lastName` string, required
    - `email` string, email, required
    - `nickname` string
    - `shouldCollectTaxInfo` boolean — Whether to require this recipient to complete tax information. Defaults to true.

## Response `201`

The recipients were created.

- object
  - `data` object
    - `success` boolean
    - `recipients` Recipient[]
      - `id` string, uuid
      - `firstName` string
      - `lastName` string
      - `email` string, email
      - `nickname` string, nullable
      - `createdAt` string, date-time
      - `onboardingUrl` string, uri, nullable — URL the recipient can use to complete onboarding, or null if already onboarded.
      - `status` 'created' | 'active' | 'missing_tax_form' | 'pending_review' | 'approved_w9' | 'approved_w8' | 'approved_1099_exempt' | 'approved_no_tax_collection' — Lifecycle status of a recipient.
      - `earnings` RecipientEarnings — Lifetime earnings totals for this recipient. Amounts are in cents.
        - `paid` integer — Total paid to date: completed payments plus recorded external payments.
        - `pending` integer — Total on the way: payments created, processing, or in review.
        - `held` integer — Total waiting on recipient action, such as accepting the payout or completing tax info.
      - `paymentMethod` RecipientPaymentMethod — Basic summary of the recipient's current active payout method.
        - `method` 'ACH' | 'PAYPAL' | 'CRYPTOCURRENCY' | 'INTERNATIONAL_BANK' | 'SWIFT' | 'KARAT' — Payout rail used to pay this recipient.
        - `currency` string — ISO currency code the recipient is paid in.

## Other responses

- `400` — The request was invalid.
- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/trykarat/apis/karat-payout-api.md) · [All operations](https://skmtc.net/trykarat/apis/karat-payout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trykarat/karat-payout-api/revisions/8941916e3707/schema)