> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/send-to-applicant.md).

# Send to Applicant

Use `POST /merchant-onboarding/{applicationId}/send-to-applicant` to send a prepared application to its applicant. The applicant receives an email with a link to finish and sign the application, and the application moves from `prepared` to `signing`.

This is the first send. To email the same invitation again later, see [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md).

{% hint style="info" %}
**Which endpoint do I call?** Send and resend are two steps of one flow. Each works for exactly one status, and the other returns `400`.

| Application status | Call                                                            | Result                                                                                  |
| ------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `prepared`         | `POST /merchant-onboarding/{applicationId}/send-to-applicant`   | First send. The application moves to `signing`.                                         |
| `signing`          | `POST /merchant-onboarding/{applicationId}/resend-to-applicant` | The invitation is emailed again with the same link. The application stays in `signing`. |
| Any other status   | Neither                                                         | Both return `400` with the current status.                                              |
| {% endhint %}      |                                                                 |                                                                                         |

#### Where this fits in the flow

1. Create and submit the application. See [Draft and Submit](https://developers.bead.xyz/onboarding/draft-and-submit.md).
2. After submit, the application moves to `preparing` while Bead gathers business information, then to `prepared`.
3. The application waits in `prepared` until someone sends it. Nothing sends it automatically. This is the point where a person on your side reviews and corrects the application.
4. Call send. The application moves to `signing` and the applicant is emailed.

An application created with skip partner review is sent automatically when it reaches `prepared`, so you do not call send for it. If that automatic send fails, the application stays in `prepared` and you can call send yourself.

#### What send does

When you call send, Bead:

1. sends any application documents that have not been sent yet
2. updates the business and owner details with the values currently on the application
3. fills any field left blank from the information gathered for the business, without replacing a value you provided
4. invites the applicant and emails them the link

If any step is refused, nobody is invited and the application stays in `prepared`. You can correct it and send again.

#### Endpoint

```http
POST /merchant-onboarding/{applicationId}/send-to-applicant
```

#### Path parameter

| Parameter       | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| `applicationId` | The onboarding application identifier returned when the application was created. |

#### Authentication and headers

Onboarding requests use API key authentication. A partner user or API key with access to the application can call this endpoint. A caller without access to the application receives `403`.

```http
X-Api-Key: {apiKey}
Accept: application/json
```

#### Request

No request body is required. Before you call send, the application must have a signer with a first name, last name, and email address.

```bash
curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/app-123exampleid/send-to-applicant \
  --header "X-Api-Key: {apiKey}" \
  --header "Accept: application/json"
```

#### Response

A successful send returns `204 No Content` with no body. The application is now in `signing`. Confirm with `GET /merchant-onboarding/applications/{applicationId}` and keep tracking it with [Get Status](https://developers.bead.xyz/onboarding/get-status.md) or [webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md).

#### Edits before you send

While the application is in `prepared`, you can still correct it. Use `PUT /merchant-onboarding/applications/drafts/{applicationId}` with the complete `merchantData`, the same way you update a Draft, and upload or replace documents. Send the corrected application only after your review is complete. Once the application is in `signing`, it can no longer be edited.

#### Send twice by mistake

Send works once. A second call on an application already in `signing` returns `400` with the current status, and the applicant is not emailed again. If two sends overlap, the second waits briefly, then returns `409` if the first is still running. To email the applicant again, use [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md).

#### If a send times out

Send performs several steps before it answers, so a timeout or dropped connection can happen after the applicant was already invited. Do not send again immediately. Call `GET /merchant-onboarding/applications/{applicationId}`. If the status is `signing`, the send went through. If it is still `prepared`, send again.

#### Error handling

| Status | Meaning                                                                                                                                                                                                | What to do                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `204`  | The application was sent and is now in `signing`.                                                                                                                                                      | Track status or wait for webhooks.                                                                                            |
| `400`  | The application is not in `prepared`, or the signer is missing a first name, last name, or email. The message names the problem.                                                                       | Check the status. If it is `signing`, use [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md). |
| `401`  | The API key is missing or invalid.                                                                                                                                                                     | Check the `X-Api-Key` header.                                                                                                 |
| `403`  | The caller does not have access to this application.                                                                                                                                                   | Use a key or user with access to the application.                                                                             |
| `404`  | Unknown `applicationId`.                                                                                                                                                                               | Check the identifier.                                                                                                         |
| `409`  | Another send of this application is still underway, or its documents are still uploading. Nothing was sent.                                                                                            | Wait a moment, check status, and send again only if it is still `prepared`.                                                   |
| `422`  | The details, a document, or the invitation was refused. The response names each refused field or document with the reason. Nobody was invited and the application stays in `prepared`.                 | Correct each named field or replace each named document, then send again.                                                     |
| `502`  | A document could not be read from storage. The response carries the `error_code` `WORTH_UNAVAILABLE`. Nothing was sent.                                                                                | Upload the document again, then send again.                                                                                   |
| `503`  | A downstream provider failed. The response carries the `error_code` `WORTH_UNAVAILABLE`. The application stays in `prepared`. When a document upload failed, `errors` names each document by category. | Retry after a short delay.                                                                                                    |

#### Best practices

* Check that the status is `prepared` before sending.
* Review and correct the application while it is in `prepared`, because it cannot be edited after the send.
* Send once, and use resend for any later email.
* After a timeout, check status before retrying.
* On `422`, show the applicant or reviewer the named fields and documents so they can be fixed, then send again.
* Match the `error_code` value `WORTH_UNAVAILABLE` exactly in your error handling. It means a provider was unavailable and a retry is safe.

#### Related pages

* [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md)
* [Draft and Submit](https://developers.bead.xyz/onboarding/draft-and-submit.md)
* [Submit Application](https://developers.bead.xyz/onboarding/submit-application.md)
* [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)
* [Webhooks for Application Events](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Reference Guide](https://developers.bead.xyz/reference-guide)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/onboarding/send-to-applicant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
