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

# Upload Document

> Upload a single document of an onboarding solicitation, identified by its tag. Supports partial uploads — once all required documents are sent, the solicitation moves automatically to documents_under_review.

<Info>
  Part of the [Onboarding Documents flow](/account/onboarding-documents-flow). The request is `multipart/form-data` with two fields: `tag` and `file`. Send **one document per call**; you may call it multiple times to upload the documents partially.
</Info>

## Path Parameters

<ParamField path="uuid" type="string" required>
  UUID of the solicitation (the `id` returned by [Create Company](/api-reference/account/create)). Must be in a status that accepts uploads (`pending_documents` or `documents_under_review`).

  * Format: UUID
  * Example: `339074a8-1834-49c5-af94-4a044248d88d`
</ParamField>

## Request Body

<Note>
  Content-Type: `multipart/form-data`.
</Note>

<ParamField body="tag" type="string" required>
  Identifier of the document being sent. Must match one of the `tag` values listed for the solicitation (delivered in the `pending_documents` webhook or returned by [List Documents](/api-reference/account/documents/list-documents)). An unrecognized tag is rejected with `422`.

  * Example: `articles_of_incorporation`
</ParamField>

<ParamField body="file" type="file" required>
  The document file.

  * Accepted formats: `pdf`, `jpg`, `jpeg`, `png`
  * Maximum size: **10 MB**
</ParamField>

## Behavior

* A successful upload sets the document's `upload_status` to `sent`.
* After each upload, if **all required** documents are `sent`, the solicitation moves **automatically** to `documents_under_review`. Optional documents do not block this transition.
* The [onboarding webhook](/api-reference/account/webhook/onboarding-documents) is fired on every upload, reflecting the updated state.
* **Resending a rejected document:** uploading a document whose `review_status` is `rejected` sets `upload_status` back to `sent` and `review_status` back to `pending`. The previous rejection `reason` is preserved in the document history and is not returned in the active document state.

<Warning>
  Upload is only allowed when the document's `upload_status` is `pending` **or** its `review_status` is `rejected`. A document already `approved` cannot be replaced, and a document already `sent` and awaiting review cannot be re-sent — both return `422`.
</Warning>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Document uploaded successfully"
  }
  ```

  ```json 422 Invalid tag theme={null}
  {
    "message": "The provided tag is not part of the solicitation documents"
  }
  ```

  ```json 422 Already approved theme={null}
  {
    "message": "Document already approved and cannot be replaced"
  }
  ```

  ```json 422 Already submitted theme={null}
  {
    "message": "Document already submitted and is awaiting review"
  }
  ```

  ```json 413 File too large theme={null}
  {
    "message": "File exceeds the maximum allowed size of 10MB"
  }
  ```

  ```json 409 Invalid status theme={null}
  {
    "message": "Solicitation does not accept document uploads in its current status"
  }
  ```

  ```json 404 Not found theme={null}
  {
    "message": "Solicitation not found"
  }
  ```
</ResponseExample>

## Errors

| Status | When                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `422`  | Tag not part of the solicitation, document already approved, document already submitted, or file format not in `pdf, jpg, jpeg, png`. |
| `413`  | File exceeds 10 MB.                                                                                                                   |
| `409`  | Solicitation is not in `pending_documents` nor `documents_under_review`.                                                              |
| `404`  | Solicitation not found or not accessible.                                                                                             |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "tag=articles_of_incorporation" \
    -F "file=@/path/to/articles_of_incorporation.pdf"
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append("tag", "articles_of_incorporation");
  form.append("file", fileInput.files[0]); // a pdf/jpg/jpeg/png up to 10 MB

  const response = await fetch(
    "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents",
    {
      method: "POST",
      headers: { Authorization: "Bearer YOUR_API_KEY" },
      body: form,
    }
  );

  const data = await response.json();
  console.log(data.message);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  data = {"tag": "articles_of_incorporation"}

  with open("articles_of_incorporation.pdf", "rb") as f:
      files = {"file": ("articles_of_incorporation.pdf", f, "application/pdf")}
      response = requests.post(url, headers=headers, data=data, files=files)

  print(response.json()["message"])
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Onboarding Documents Integration" icon="file-arrow-up" href="/account/onboarding-documents-flow">
    Understand the full flow
  </Card>

  <Card title="List Documents" icon="list-check" href="/api-reference/account/documents/list-documents">
    Query state and review history
  </Card>
</CardGroup>