> ## Documentation Index > Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Attach Documents > Adds supporting documents to a payer name that is still in review. Unlike an update, this does not reset the review status or clear the reviewer note. Documents cannot be added once a decision has been made. Adds supporting documents to a payer name that is still in review — the usual answer to a reviewer asking for better evidence. ## Example Request ```bash theme={null} curl -X POST "https://api.rolla.xyz/api/v1/external/payer-names/9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f/documents" \ -H "X-API-Key: your_api_key_here" \ -F "documents=@certificate-of-incorporation.pdf" \ -F "documents=@director-id.jpg" \ -F "documentDescriptions=Certificate of incorporation" \ -F "documentDescriptions=Director ID" ``` Repeat `documents` once per file. `documentDescriptions` labels them positionally: the first description belongs to the first file. A file with no description is stored unlabelled. ## Example Response The full payer name, with the new documents included. ```json theme={null} { "status": 201, "message": "Documents attached", "success": true, "data": { "id": "9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f", "type": "business", "name": "Acme Trading Ltd", "firstName": null, "lastName": null, "registrationNumber": "RC1234567", "registrationDate": "2019-04-02", "country": "NG", "address": { "line1": "14 Marina Road", "city": "Lagos", "state": "Lagos", "postalCode": "101001" }, "status": "pending_review", "isDefault": false, "decisionNote": null, "documents": [ { "id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091", "fileName": "certificate-of-incorporation.pdf", "description": "Certificate of incorporation", "fileType": "application/pdf", "fileSize": 284122, "downloadUrl": "https://files.rolla.xyz/payer_name_docs/...", "createdAt": "2026-09-03T10:20:00.000Z" }, { "id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809112", "fileName": "director-id.jpg", "description": "Director ID", "fileType": "image/jpeg", "fileSize": 91233, "downloadUrl": "https://files.rolla.xyz/payer_name_docs/...", "createdAt": "2026-09-03T10:20:00.000Z" } ], "metadata": { "vendor_id": "V-4471" }, "createdAt": "2026-09-01T09:14:22.000Z", "updatedAt": "2026-09-03T10:20:00.000Z" } } ``` ## Accepted files | Constraint | Value | | ------------ | -------------------------------------------- | | Formats | PDF, JPEG, PNG, Word (`.doc`, `.docx`) | | Maximum size | 10MB per file | | Count | No limit; attach as many as the review needs | Anything else is rejected with a `400`, and no file in the call is stored. Unlike an [update](/api-reference/endpoint/payer-names/update), attaching documents does **not** reset the review status or clear the reviewer's note. The name stays where it is, with more evidence on it. ## Errors | Status | Cause | | ------ | ----------------------------------------------------------------------------- | | `400` | No file was sent, or a file is too large or of an unsupported type | | `403` | Named Payouts are not enabled for this account (`code: PAYER_NAMES_DISABLED`) | | `404` | No such payer name on this account | | `409` | The payer name is no longer in review, so documents can no longer be added | ## OpenAPI ````yaml POST /payer-names/{payerNameId}/documents openapi: 3.1.0 info: title: Rolla Developer API description: >- API for programmatic transaction management on the Rolla platform. Monetary `amount` fields use the smallest unit of the referenced currency unless an endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents = USD 1.00**). version: 1.0.0 servers: - url: https://api.rolla.xyz/api/v1/external description: Production server security: - apiKeyAuth: [] paths: /payer-names/{payerNameId}/documents: post: summary: Attach Documents description: >- Adds supporting documents to a payer name that is still in review. Unlike an update, this does not reset the review status or clear the reviewer note. Documents cannot be added once a decision has been made. operationId: attachPayerNameDocuments parameters: - name: payerNameId in: path required: true description: The payer name id. schema: type: string format: uuid requestBody: required: true content: multipart/form-data: schema: type: object required: - documents properties: documents: type: array items: type: string format: binary description: >- Supporting files. PDF, JPEG, PNG or Word (`.doc`, `.docx`), up to 10MB each. Repeat the field to attach more than one. documentDescriptions: type: array items: type: string description: >- Labels for the files, positionally: the first value labels the first file. Repeat the field once per file. example: documentDescriptions: - Certificate of incorporation - Director ID responses: '201': description: >- Documents attached. The full payer name is returned, with the new documents included. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code, repeated in the body example: 201 message: type: string example: Documents attached success: type: boolean example: true data: $ref: '#/components/schemas/PayerName' example: status: 201 message: Documents attached success: true data: id: 9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f type: business name: Acme Trading Ltd firstName: null lastName: null registrationNumber: RC1234567 registrationDate: '2019-04-02' country: NG address: line1: 14 Marina Road city: Lagos state: Lagos postalCode: '101001' status: pending_review isDefault: false decisionNote: null documents: - id: 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091 fileName: certificate-of-incorporation.pdf description: Certificate of incorporation fileType: application/pdf fileSize: 284122 downloadUrl: https://files.rolla.xyz/payer_name_docs/... createdAt: '2026-09-03T10:20:00.000Z' - id: 3c4d5e6f-7081-4923-ab4c-5d6e7f809112 fileName: director-id.jpg description: Director ID fileType: image/jpeg fileSize: 91233 downloadUrl: https://files.rolla.xyz/payer_name_docs/... createdAt: '2026-09-03T10:20:00.000Z' metadata: vendor_id: V-4471 createdAt: '2026-09-01T09:14:22.000Z' updatedAt: '2026-09-03T10:20:00.000Z' '400': description: >- Bad request — no file was sent, or a file is too large or of an unsupported type. No file in the call is stored. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 400 message: No documents were provided '401': description: Unauthorized — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — Named Payouts are not enabled for this account content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 403 message: >- Payer names are not enabled for this account. Contact your Rolla account manager to turn them on. code: PAYER_NAMES_DISABLED '404': description: Not found — no such payer name on this account content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 404 message: Payer name not found '409': description: >- Conflict — the payer name is no longer in review, so documents can no longer be added content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 409 message: >- Documents can only be added while a payer name is under review (status: approved) components: schemas: PayerName: type: object description: >- A payer name: the name a beneficiary sees on a payout you send. Responses are camelCase; request bodies are snake_case. properties: id: type: string format: uuid example: 9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f type: type: string enum: - individual - business example: business name: type: string description: The name shown to the beneficiary. example: Acme Trading Ltd firstName: type: string nullable: true description: Individuals only; `null` for a business. lastName: type: string nullable: true description: Individuals only; `null` for a business. registrationNumber: type: string nullable: true example: RC1234567 registrationDate: type: string nullable: true format: date example: '2019-04-02' country: type: string description: ISO 3166-1 alpha-2 country code. example: NG address: type: object properties: line1: type: string example: 14 Marina Road city: type: string example: Lagos state: type: string example: Lagos postalCode: type: string nullable: true example: '101001' status: type: string enum: - pending_review - changes_requested - processing - active - action_required - rejected - archived description: >- Where the payer name has got to: Rolla review and provider registration collapsed into one value. Only `active` is fully usable. Note that the `status` query filter on List Payer Names takes review statuses instead, where `approved` covers `processing`, `active` and `action_required`. example: active isDefault: type: boolean description: Applied to payouts that do not name a payer name. example: false decisionNote: type: string nullable: true description: >- The reviewer's note, verbatim. Set on `changes_requested` and `rejected`, cleared on an update. documents: type: array items: $ref: '#/components/schemas/PayerNameDocument' metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: >- Your own flat key/value data, echoed back verbatim. Omitted entirely when you have not set any. example: vendor_id: V-4471 createdAt: type: string format: date-time example: '2026-09-01T09:14:22.000Z' updatedAt: type: string format: date-time example: '2026-09-02T11:02:41.000Z' Error: type: object required: - status - message description: >- Error envelope. Some errors add further top-level fields (for example `accountBlocked`, `provider`, `missingFields`); the endpoint documents them where they apply. additionalProperties: true properties: status: type: integer description: HTTP status code, repeated in the body as a number example: 400 message: type: string description: Human-readable description of what went wrong example: Validation failed code: type: string description: >- Machine-readable error code, present on some errors only. See the Errors concept page for the taxonomy. example: ACCOUNT_RESTRICTED errors: type: array description: 'Present on `400` validation failures: one entry per offending field' items: type: object properties: path: type: array items: type: string example: - amount message: type: string example: >- amount must be a whole number of smallest currency units (e.g. cents) PayerNameDocument: type: object description: >- A supporting document attached to a payer name. Read by Rolla review only; never forwarded to a payout rail. properties: id: type: string format: uuid example: 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091 fileName: type: string example: certificate-of-incorporation.pdf description: type: string nullable: true description: >- The label you sent in `documentDescriptions`, or `null` for an unlabelled file. example: Certificate of incorporation fileType: type: string description: MIME type. example: application/pdf fileSize: type: integer description: Size in bytes. example: 284122 downloadUrl: type: string description: >- Signed URL, valid for 1 hour from the time the response was generated. An empty string when the stored object is no longer available. example: https://files.rolla.xyz/payer_name_docs/... createdAt: type: string format: date-time example: '2026-09-01T09:14:22.000Z' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: Your Rolla API key ````