> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a file

> Required API-key scope: depends on `purpose`.

Uploads a file you can use in another request, such as a receipt for a card transaction. Send `multipart/form-data` with `purpose` first, then `file`.

| `purpose` | Use it for | Scope | File types | Max size |
| --- | --- | --- | --- | --- |
| `card_receipt` | [Attach a receipt](/api-reference/cards/attach-a-receipt-to-a-card-account-activity) to a card transaction | `card_activities:write` | PDF, JPEG, PNG, GIF, HEIC | 10 MB |

**After you upload**

1. The file starts with `status: checking` while we scan it for malware.
2. Call [Retrieve a file](/api-reference/files/retrieve-a-file) every 2 to 5 seconds until `status` is `ready`. This can take up to 5 minutes.
3. Attach it within 24 hours.

| Error | When |
| --- | --- |
| `400` | There is no file, the file is empty, or there is more than one file. |
| `413` | The file is over 10 MB. |
| `FILE_TYPE_NOT_SUPPORTED` | The file isn't an allowed type. We check the content, not the file name. |
| `503` | We couldn't store the file right now. Wait a few seconds, then upload it again. If you retry automatically, back off exponentially with jitter and stop after a few tries. |

You don't need an `Idempotency-Key`. Uploading twice, including after a `503`, can create a second file, which expires on its own. Only attach the `id` from a successful upload.

See [Attach receipts to card transactions](/guides/attach-receipts-to-card-transactions).



## OpenAPI

````yaml /openapi/2026-11-05.json post /2026-11-05/files
openapi: 3.1.0
info:
  title: Reap Business Account API
  description: >

    # Introduction


    The Reap Business Account API lets you manage cards, spend and Treasury

    funding for your Business Account from your own systems. Every endpoint is

    authenticated with an API key sent in the `x-api-key` header and versioned

    with a date in the URL (`/2026-11-05/...`).


    Guides, concepts and the full setup reference live on the docs site:

    [direct-api.reap.global](https://direct-api.reap.global).



    ## Errors


    All errors share a single JSON envelope:


    ```json

    {
      "statusCode": 400,
      "type": "INVALID_REQUEST_ERROR",
      "code": "SPEND_CAP_TOO_LOW",
      "message": "Spend cap cannot be lower than the amount already spent on this card.",
      "param": "spendCap",
      "requestId": "01H..."
    }

    ```


    - `statusCode`: HTTP status, duplicated in the body.

    - `type`: coarse category, **always present**. Branch on this for
    retry/re-auth decisions.

    - `code`: stable, machine-readable identifier. Present only for
    programmatically-actionable errors.

    - `message`: human-readable explanation, safe to surface to users.

    - `param`: offending field for validation errors (optional).

    - `details`: structured extra context such as validation issues or required
    API-key scopes (optional).

    - `requestId`: correlation id; include it when contacting support
    (optional).


    The specific error codes each endpoint can return are documented on that

    endpoint's responses below.


    ### Error types


    | Type | Description |

    | --- | --- |

    | `INVALID_REQUEST_ERROR` | The request was rejected due to invalid input, a
    missing resource, or a business-rule violation (HTTP 400/404/409/422). |

    | `AUTHENTICATION_ERROR` | Authentication is missing or invalid (HTTP 401).
    |

    | `PERMISSION_ERROR` | The caller is authenticated but not permitted to
    perform the action (HTTP 403). |

    | `RATE_LIMIT_ERROR` | Too many requests; retry after a delay (HTTP 429). |

    | `API_ERROR` | An unexpected error occurred on our side (HTTP 5xx). |

    | `UPSTREAM_ERROR` | An upstream service returned an error (HTTP 502/503). |
  version: '2026-11-05'
  contact: {}
servers:
  - url: https://api.global.direct.reap.global
security: []
tags: []
paths:
  /2026-11-05/files:
    post:
      tags:
        - Files
      summary: Upload a file
      description: >-
        Required API-key scope: depends on `purpose`.


        Uploads a file you can use in another request, such as a receipt for a
        card transaction. Send `multipart/form-data` with `purpose` first, then
        `file`.


        | `purpose` | Use it for | Scope | File types | Max size |

        | --- | --- | --- | --- | --- |

        | `card_receipt` | [Attach a
        receipt](/api-reference/cards/attach-a-receipt-to-a-card-account-activity)
        to a card transaction | `card_activities:write` | PDF, JPEG, PNG, GIF,
        HEIC | 10 MB |


        **After you upload**


        1. The file starts with `status: checking` while we scan it for malware.

        2. Call [Retrieve a file](/api-reference/files/retrieve-a-file) every 2
        to 5 seconds until `status` is `ready`. This can take up to 5 minutes.

        3. Attach it within 24 hours.


        | Error | When |

        | --- | --- |

        | `400` | There is no file, the file is empty, or there is more than one
        file. |

        | `413` | The file is over 10 MB. |

        | `FILE_TYPE_NOT_SUPPORTED` | The file isn't an allowed type. We check
        the content, not the file name. |

        | `503` | We couldn't store the file right now. Wait a few seconds, then
        upload it again. If you retry automatically, back off exponentially with
        jitter and stop after a few tries. |


        You don't need an `Idempotency-Key`. Uploading twice, including after a
        `503`, can create a second file, which expires on its own. Only attach
        the `id` from a successful upload.


        See [Attach receipts to card
        transactions](/guides/attach-receipts-to-card-transactions).
      operationId: uploadFile
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - purpose
                - file
              properties:
                purpose:
                  type: string
                  enum:
                    - card_receipt
                  description: >-
                    Send before the file field. `card_receipt` needs the
                    `card_activities:write` API-key scope.
                file:
                  type: string
                  format: binary
                  description: >-
                    For `card_receipt`: PDF, JPEG, PNG, GIF or HEIC, up to 10
                    MB.
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
              examples:
                checking:
                  summary: File uploaded, malware scan running
                  value:
                    id: 8f14e45f-ceea-4e67-a1b2-0f3c9d7a1b11
                    purpose: card_receipt
                    filename: null
                    size: 48213
                    contentType: application/pdf
                    status: checking
                    createdAt: '2026-10-29T01:00:00.000Z'
        '400':
          description: '`BAD_REQUEST`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BAD_REQUEST:
                  summary: BAD_REQUEST
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    message: Bad request.
        '401':
          description: '`UNAUTHORIZED`, `AUTH_CREDENTIAL_MISSING`, `API_KEY_INVALID`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  summary: UNAUTHORIZED
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    message: Authentication required.
                AUTH_CREDENTIAL_MISSING:
                  summary: AUTH_CREDENTIAL_MISSING
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: AUTH_CREDENTIAL_MISSING
                    message: Authentication is required.
                API_KEY_INVALID:
                  summary: API_KEY_INVALID
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: API_KEY_INVALID
                    message: API key is invalid.
        '403':
          description: '`FEATURE_NOT_ENABLED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  summary: FORBIDDEN
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    message: You do not have permission to perform this action.
                API_KEY_IP_NOT_ALLOWED:
                  summary: API_KEY_IP_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: API_KEY_IP_NOT_ALLOWED
                    message: Request IP is not allowed for this API key.
                AUTH_INSUFFICIENT_PERMISSIONS:
                  summary: AUTH_INSUFFICIENT_PERMISSIONS
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_INSUFFICIENT_PERMISSIONS
                    message: Insufficient permissions.
                    details:
                      requiredScopes:
                        - <required-scope>
                AUTH_METHOD_NOT_ALLOWED:
                  summary: AUTH_METHOD_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_METHOD_NOT_ALLOWED
                    message: >-
                      This endpoint does not accept the credential type
                      provided.
                FEATURE_NOT_ENABLED:
                  summary: FEATURE_NOT_ENABLED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: FEATURE_NOT_ENABLED
                    message: This feature is not enabled for your account.
        '413':
          description: '`PAYLOAD_TOO_LARGE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PAYLOAD_TOO_LARGE:
                  summary: PAYLOAD_TOO_LARGE
                  value:
                    statusCode: 413
                    type: INVALID_REQUEST_ERROR
                    message: The file is too large.
        '422':
          description: '`FILE_TYPE_NOT_SUPPORTED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FILE_TYPE_NOT_SUPPORTED:
                  summary: FILE_TYPE_NOT_SUPPORTED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: FILE_TYPE_NOT_SUPPORTED
                    message: The file's content is not a supported file type.
        '429':
          description: '`API_KEY_RATE_LIMITED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                API_KEY_RATE_LIMITED:
                  summary: API_KEY_RATE_LIMITED
                  value:
                    statusCode: 429
                    type: RATE_LIMIT_ERROR
                    code: API_KEY_RATE_LIMITED
                    message: API key rate limit exceeded.
        '500':
          description: '`INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INTERNAL_ERROR:
                  summary: INTERNAL_ERROR
                  value:
                    statusCode: 500
                    type: API_ERROR
                    message: An unexpected error occurred.
        '503':
          description: '`SERVICE_UNAVAILABLE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SERVICE_UNAVAILABLE:
                  summary: SERVICE_UNAVAILABLE
                  value:
                    statusCode: 503
                    type: UPSTREAM_ERROR
                    message: The service is temporarily unavailable.
        '504':
          description: '`UPSTREAM_TIMEOUT`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_TIMEOUT:
                  summary: UPSTREAM_TIMEOUT
                  value:
                    statusCode: 504
                    type: UPSTREAM_ERROR
                    code: UPSTREAM_TIMEOUT
                    message: >-
                      An upstream service did not respond in time. If this
                      request changes data, it may still have been applied, so
                      fetch the resource before you retry.
      security:
        - apiKey: []
components:
  schemas:
    File:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: >-
            The file ID. Use it to retrieve the file and to attach it as a
            receipt.
        purpose:
          type: string
          enum:
            - card_receipt
          description: >-
            What the file is for. `card_receipt` is a receipt you attach to a
            card transaction.
        filename:
          description: >-
            The file name we stored. It is null until the file is `ready`, and
            the extension matches the real file type.
          type:
            - string
            - 'null'
        size:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: The file size in bytes.
        contentType:
          type: string
          description: >-
            The file type we detected from its content, for example
            `application/pdf`.
        status:
          type: string
          enum:
            - checking
            - ready
            - blocked
            - failed
          description: >-
            The malware scan result: `checking` (still scanning), `ready` (safe
            to attach), `blocked` (a threat was found) or `failed` (the scan
            could not finish).
        reason:
          description: 'Why the file is `blocked` or `failed`: `threat` or `unscannable`.'
          type: string
          enum:
            - threat
            - unscannable
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: When the file was uploaded, in UTC.
      required:
        - id
        - purpose
        - filename
        - size
        - contentType
        - status
        - createdAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code, repeated in the body for convenience.
        type:
          type: string
          enum:
            - INVALID_REQUEST_ERROR
            - AUTHENTICATION_ERROR
            - PERMISSION_ERROR
            - RATE_LIMIT_ERROR
            - API_ERROR
            - UPSTREAM_ERROR
          description: >-
            The broad kind of error, for example `RATE_LIMIT_ERROR`. It's always
            present: use it to decide whether to retry, re-authenticate or fix
            the request.
        code:
          description: >-
            A stable, machine-readable error code, for example
            `CARD_CREATION_REQUIRES_DEPOSIT`. It's present when there's a
            specific action you can take, and each endpoint lists the codes it
            can return.
          type: string
        message:
          type: string
          description: >-
            A plain-English explanation of the error that's safe to show to your
            users.
        param:
          description: >-
            The request field that caused a validation error, for example
            `spendCap`.
          type: string
        details:
          description: >-
            Extra structured information, such as the list of validation issues
            or the API-key scopes your key is missing.
        requestId:
          description: >-
            A unique ID for this request. Include it when you contact Reap
            Support so the team can find it.
          type: string
      required:
        - statusCode
        - type
        - message
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Enter your API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.