---
title: "Create a recipient invite"
method: POST
path: "/recipients/invites"
tags: ["Recipient Invites"]
---

# Create a recipient invite

`POST /recipients/invites`

Create an invite for a recipient to submit their payment details. Supply a recipientId to invite an existing recipient; omit it to invite someone new, in which case the recipient is created when the invitee completes onboarding.

## Request body

- CreateRecipientInviteApiRequest — Request body for creating a recipient invite.
  - `contactEmail` string, required — Contact email the invite is sent to. When 'recipientId' is present, updates the recipient's contact email to this value.
  - `name` string, nullable — Name the invite is created for. This field is required when 'recipientId' is absent. When 'recipientId' is present, this field is optional and updates the recipient's name to this value.
  - `notes` string, nullable — Optional notes shown to the recipient.
  - `organizationNameOnRequest` string, nullable — Optional organization name to display on the request.
  - `paymentMethods` PaymentMethod[], required — Payment methods the recipient may submit details for.
  - `recipientId` string, uuid, nullable — The recipient to send the invite to.
  - `requireTaxDocument` boolean, required — Whether the recipient must upload a tax document.
  - `sendEmail` boolean, required — When true, sends an Email to the invitee. When false, does not send an email to the invitee.

## Response `201`

- RecipientInviteApiResponse
  - `contactEmail` string, required — Recipient contact email the invite was created for.
  - `createdAt` string, yyyy-mm-ddThh:MM:ssZ, required — When the invite was created.
  - `expiresAt` string, yyyy-mm-ddThh:MM:ssZ, nullable — When the invite expires, if it has an expiry.
  - `id` string, required — The invite's id, also embedded in 'onboardingUrl'.
  - `name` string, required — Recipient name the invite was created for.
  - `notes` string, nullable — Notes shown to the recipient, if any.
  - `onboardingUrl` string, required — URL where the recipient submits their payment details.
  - `paymentMethods` PaymentMethod[], required — Payment methods the recipient may submit details for.
  - `recipientId` string, uuid, nullable — The existing recipient this invite is for, if any.
  - `requireTaxDocument` boolean, required — Whether the recipient must upload a tax document.
  - `status` 'created' | 'completed' | 'expired', required — Status of the invite.

## Other responses

- `400` — Invalid `body`

---

[API](https://skmtc.net/mercurytechnologies/apis/mercury-api.md) · [All operations](https://skmtc.net/mercurytechnologies/apis/mercury-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mercurytechnologies/mercury-api/revisions/0bdf4a496e03/schema)