---
title: "Retrieve upload structure"
description: "Check an uploaded PDF or DOCX before you send it: page sizes, the [[placeholders]] SignatureAPI detects with their positions, and the DOCX template fields."
canonical: "https://signatureapi.com/docs/api/resources/uploads/structure"
source: "https://signatureapi.com/docs/api/resources/uploads/structure.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Retrieve upload structure

Check an uploaded PDF or DOCX before you send it: page sizes, the [[placeholders]] SignatureAPI detects with their positions, and the DOCX template fields.

_Last verified against API version 1.18.0._

Retrieve the structure SignatureAPI detects in an uploaded file: the size of each page, every `[[place_key]]` placeholder with its position, and, for DOCX files, every `{{field}}` template field.

Use it after [creating an upload](https://signatureapi.com/docs/api/resources/uploads/create) and before creating an envelope, to confirm that placeholders and template fields are found where you expect and that their keys are valid. SignatureAPI runs the same detection when you create an envelope.

The endpoint works for PDF and DOCX uploads. A PNG upload returns an [invalid-file-format](https://signatureapi.com/docs/v1/errors/invalid-file-format) error.

## Path Parameters

#### `upload_id` (string, path, required)

The unique identifier of the upload, such as `upl_3JJz6t1o8A5YjX5VpnX27Z`.

## Returns

Returns a `200 OK` status code and the structure of the file, or an [error](https://signatureapi.com/docs/api/errors) otherwise. All positions and sizes are in points (1/72 inch).

#### `format` (enum, required)

The file format: `pdf` or `docx`.

#### `page_count` (integer, required)

The number of pages in the file.

#### `placeholders` (array, required)

The `[[place_key]]` placeholders found in the file, in document order. Each placeholder has:

- `key`: the text between the double brackets.
- `page_number`: the page the placeholder is on, starting at 1.
- `left` and `top`: the distances from the left and top edges of the page to the placeholder's bottom-left corner, measured the same way as [fixed positions](https://signatureapi.com/docs/api/resources/places/positioning#fixed-positions).
- `width` and `height`: the size of the placeholder text.
- `errors`: problems with the placeholder. An empty array means the placeholder is valid. A key that isn't 1 to 32 lowercase letters, digits and underscores starting with a letter gets an error, and so does a key used by more than one placeholder (`placeholder key is repeated.`).

#### `fields` (array)

DOCX only. The `{{field}}` [template fields](https://signatureapi.com/docs/api/resources/documents/templates) found in the file, with the same `key`, `page_number`, `left`, `top`, `width`, `height` and `errors` properties as a placeholder. A nested key uses dot notation, such as `person.name`, and a key nested more than 10 levels deep gets an error.

#### `pages` (array, required)

One entry per page, with its `page_number`, `width` and `height`. A US Letter page is 612 × 792 points and an A4 page is 595 × 842.

## Errors

The file is analyzed with the same [document limits](https://signatureapi.com/docs/api/resources/documents/object#limits) as an envelope document. A file that fails analysis returns one of these `422` errors: [too-many-pages](https://signatureapi.com/docs/v1/errors/too-many-pages), [too-many-places](https://signatureapi.com/docs/v1/errors/too-many-places), [cannot-parse-file](https://signatureapi.com/docs/v1/errors/cannot-parse-file), [empty-document](https://signatureapi.com/docs/v1/errors/empty-document), [no-pages](https://signatureapi.com/docs/v1/errors/no-pages), [cannot-convert](https://signatureapi.com/docs/v1/errors/cannot-convert) or [cannot-download-file](https://signatureapi.com/docs/v1/errors/cannot-download-file). An unknown `upload_id` returns [not-found](https://signatureapi.com/docs/v1/errors/not-found).

### Example: PDF

A two-page PDF with two placeholders on page 2.

```http
GET /v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
```

Response 200 OK:

```json
{
  "format": "pdf",
  "page_count": 2,
  "placeholders": [
    {
      "key": "client_signs_here",
      "page_number": 2,
      "left": 72,
      "top": 540,
      "width": 118.4,
      "height": 14.2,
      "errors": []
    },
    {
      "key": "provider_signs_here",
      "page_number": 2,
      "left": 330,
      "top": 540,
      "width": 129.6,
      "height": 14.2,
      "errors": []
    }
  ],
  "pages": [
    {
      "page_number": 1,
      "width": 612,
      "height": 792
    },
    {
      "page_number": 2,
      "width": 612,
      "height": 792
    }
  ]
}
```

Response 404 Not Found:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Could not find Upload upl_3JJz6t1o8A5YjX5VpnX27Z."
}
```

### Example: DOCX template

A one-page Word template with four template fields and one placeholder.

```http
GET /v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
```

Response 200 OK:

```json
{
  "format": "docx",
  "page_count": 1,
  "placeholders": [
    {
      "key": "candidate_signs_here",
      "page_number": 1,
      "left": 72,
      "top": 610.5,
      "width": 142.3,
      "height": 14.2,
      "errors": []
    }
  ],
  "fields": [
    {
      "key": "candidateName",
      "page_number": 1,
      "left": 120.4,
      "top": 180.2,
      "width": 96.1,
      "height": 14.2,
      "errors": []
    },
    {
      "key": "position",
      "page_number": 1,
      "left": 160.8,
      "top": 230.6,
      "width": 58.3,
      "height": 14.2,
      "errors": []
    },
    {
      "key": "startDate",
      "page_number": 1,
      "left": 148.2,
      "top": 252.6,
      "width": 62.7,
      "height": 14.2,
      "errors": []
    },
    {
      "key": "salary",
      "page_number": 1,
      "left": 134.5,
      "top": 274.6,
      "width": 44.9,
      "height": 14.2,
      "errors": []
    }
  ],
  "pages": [
    {
      "page_number": 1,
      "width": 612,
      "height": 792
    }
  ]
}
```

### Example: Repeated placeholder

A PDF that uses the same placeholder twice.

```http
GET /v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
```

Response 200 OK:

```json
{
  "format": "pdf",
  "page_count": 1,
  "placeholders": [
    {
      "key": "client_signs_here",
      "page_number": 1,
      "left": 72,
      "top": 640,
      "width": 90.2,
      "height": 14.2,
      "errors": [
        "placeholder key is repeated."
      ]
    },
    {
      "key": "client_signs_here",
      "page_number": 1,
      "left": 330,
      "top": 640,
      "width": 90.2,
      "height": 14.2,
      "errors": [
        "placeholder key is repeated."
      ]
    }
  ],
  "pages": [
    {
      "page_number": 1,
      "width": 612,
      "height": 792
    }
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
