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

# Upload

Upload one or more files to be signed. Save the returned `fileId` or `externalId` for use in future API requests.

<Tip>
  Post the raw file (do not convert to base64) with a `Content-Type` of `application/pdf` for PDF or `application/octet-stream` for DOCX.
</Tip>

<Tip>
  You must add a `Content-Disposition` header with the filename to allow any of the supported file conversions to PDF.
</Tip>

## Request

<Tabs>
  <Tab title="PDF">
    ```http Request theme={null}
    POST /files/upload
    Content-Type: multipart/form-data

    Content-Disposition: form-data; filename="document.pdf"
    Content-Type: application/pdf

    <FILE_CONTENTS>
    ```
  </Tab>

  <Tab title="DOCX">
    ```http Request highlight={5} theme={null}
    POST /files/upload
    Content-Type: multipart/form-data

    Content-Disposition: form-data; filename="document.docx"
    Content-Type: application/octet-stream

    <FILE_CONTENTS>
    ```
  </Tab>

  <Tab title="UTF-8">
    ```http Request highlight={4} theme={null}
    POST /files/upload
    Content-Type: multipart/form-data

    Content-Disposition: form-data; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf
    Content-Type: application/pdf

    <FILE_CONTENTS>
    ```
  </Tab>
</Tabs>

### Query parameters

<ParamField query="type" type="string" default="temporary">
  | Value     | Description                                                                                |
  | :-------- | :----------------------------------------------------------------------------------------- |
  | temporary | The file will be stored temporarily and deleted if not added to a package within 24 hours. |
</ParamField>

<ParamField query="externalId" type="string">
  Provide an external ID that can be used to reference the file.

  This `externalId` will be stored with the document during `packages/add` request. It will then be included in future:

  * `packages/status` requests
  * `document` webhook events

  <Warning>
    If a user replaces a document after the package was created the `externalId` will no longer be associated with the document.
  </Warning>
</ParamField>

## Response

<ResponseField name="files" type="object[]">
  List of uploaded files with their statuses.

  <Expandable title="properties">
    <ResponseField name="fileId" type="string">
      Unique identifier for the uploaded file.
    </ResponseField>

    <ResponseField name="externalId" type="string">
      External system identifier for the file, if available.
    </ResponseField>

    <ResponseField name="fileName" type="string">
      Original filer name of the uploaded file.
    </ResponseField>

    <ResponseField name="isInvalid" type="boolean">
      Indicates if the file is invalid or corrupted.
    </ResponseField>

    <ResponseField name="isConverted" type="boolean">
      Indicates if the file was successfully converted to the required format.
    </ResponseField>

    <ResponseField name="isNotSupported" type="boolean">
      Indicates if the file type is not supported.
    </ResponseField>

    <ResponseField name="isPasswordProtected" type="boolean">
      Indicates if the file is password protected.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error code or message related to the file upload or processing.
    </ResponseField>

    <ResponseField name="message" type="string">
      Additional message or details about the file status.
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of stored file.

      | Value     | Description                                                                                |
      | :-------- | :----------------------------------------------------------------------------------------- |
      | temporary | The file will be stored temporarily and deleted if not added to a package within 24 hours. |
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

<Danger>
  **PDF Error: PDF header not found.**

  If a `PDF Error: PDF header not found.` error is returned, make sure you
  are sending the file as binary data.
</Danger>

## Notes

<Note>
  **Encoding filename using UTF-8**

  Replace filename (ISO-8859-1) in Content-Disposition header with filename\*=UTF-8''

  * Place two separate single quotes after the UTF-8, not one double quote.
  * You must URL Encode the filename to escape the UTF-8 characters and any whitespaces.
  * Do not wrap the encoded filename with double quotes.
  * Do not add a semicolon after the encoded filename.

  **Example**

  résumé.pdf `filename*=UTF-8''r%C3%A9sum%C3%A9.pdf`

  For more information, refer to [RFC 5987](https://tools.ietf.org/html/rfc5987)
</Note>