Skip to content

Uploads

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.

GET
/ v1 / uploads / {upload_id} / structure

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 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 error.

Path Parameters

upload_idstringrequired

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 otherwise. All positions and sizes are in points (1/72 inch).

formatenum

The file format: pdf or docx.

page_countinteger

The number of pages in the file.

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.
  • 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.).
fieldsarray

DOCX only. The {{field}} template fields 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.

pagesarray

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 as an envelope document. A file that fails analysis returns one of these 422 errors: too-many-pages, too-many-places, cannot-parse-file, empty-document, no-pages, cannot-convert or cannot-download-file. An unknown upload_id returns not-found.

GET /v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
{
  "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
    }
  ]
}

Errors every call can return are in Errors and Authentication.