> For the complete documentation index, see [llms.txt](https://api-docs.rightsline.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.rightsline.com/config/data-types/external-document.md).

# External Document

Configures a field to have a file dialog that the user can upload one or more files with

`"allowMultiple"` can be set to true to allow more than one file to be uploaded to a single field.

Allows all file types to be uploaded.

| Value Precision | is AllowMultiple respected? | Has validation? |
| --------------- | --------------------------- | --------------- |
| -               | Yes                         | Yes             |

### External Document Data Type Definition

```json
{
     "fields" : [
     	{
	    "fieldName": "External Doc",
            "label": "external_doc",
            "required": false,
            "maxLength": 10000,
            "editable": true,
            "dataType": "ExternalDocument",
            "allowMultiple": false,
            "listOfValues": []
	},
        ...
    ]
}  
```

### Creating an entity with an external document

To create an entity with an external document characteristic, follow the following steps:

1. Request temporary credentials.
2. Build a POST request to one of the create entity endpoints, where the body has the following structure. Take note of the "external\_doc" characteristic, where we are passing the file name of the document as the value.

```json
{
    "title": "My New Deal",
    "template": {
        "templateId": 2
    },
    "characteristics": {
        "external_doc": "my_document.pdf"
    }
}
```

3. If your request is successful, you will receive the new entity ID in the response.
4. You will then retrieve your new entity using a GET request with the entity ID.
5. For the "external\_doc" characteristic, a URL will be returned in the response.

```
...
"characteristics": {
        "external_doc": "https://....cloudfront.net/..."
    },
...
```

6. You can then use this URL to upload the document binary directly to our AWS S3 storage, by doing a PUT request with the binary data of your document. In Postman, this would look like:

<div data-with-frame="true"><figure><img src="https://2092511861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8zuJdsrsd_MeaESXRx-3778137224%2Fuploads%2FlNCYzeMBmlyWeD7PVoGB%2Fimage.png?alt=media&amp;token=9297d21f-1872-4689-8949-e41de6ad38bd" alt=""><figcaption></figcaption></figure></div>

### Retrieving an External Document

Once an external document has been uploaded, you can retrieve it using the File API. The API supports downloading the file directly or obtaining a temporary signed URL to access the file.

#### **Download an External Document**

To download an uploaded external document, send a GET request to the File API using the file's ID.

Endpoint:

```
GET /v4/file/{id}/data
```

Replace `{id}` with the ID of the uploaded file.

The API returns the file's binary content rather than a JSON response. The response includes the appropriate content type and download filename.

To download a specific revision of a file, use:

```
GET /v4/file/{id}-{revisionId}/data
```

#### **Retrieve a Temporary Download URL**

Instead of downloading the file directly through the API, you can request a temporary signed URL to access the uploaded document.

Endpoint:

```
GET /v4/file/{id}/url
```

Replace `{id}` with the uploaded file's ID.

The API returns a JSON response containing a signed URL and its expiration time. The URL is valid for approximately one hour. The expiration timestamp is provided in UTC. Clients should retrieve a new signed URL before the reported expiration time to avoid using an expired link.

Example response:

```
{
  "id": 12345,
  "link": {
    "url": "https://example.cloudfront.net/...",
    "expiration": "2026-11-17T15:42:07.318Z"
  }
}
```

To retrieve a signed URL for a specific revision, use:

```
GET /v4/file/{id}-{revisionId}/url
```
