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.
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
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).
The file format: pdf or docx.
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.leftandtop: 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.widthandheight: 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.).
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.
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_KEYnpx signatureapi uploads inspect upl_3JJz6t1o8A5YjX5VpnX27Z{
"name": "inspect_upload",
"arguments": {
"upload_id": "upl_3JJz6t1o8A5YjX5VpnX27Z"
}
}GET /v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEYnpx signatureapi uploads inspect upl_1sAAaVfabdt0esVjmSTmLA{
"name": "inspect_upload",
"arguments": {
"upload_id": "upl_1sAAaVfabdt0esVjmSTmLA"
}
}GET /v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEYnpx signatureapi uploads inspect upl_3JJz6t1o8A5YjX5VpnX27Z{
"name": "inspect_upload",
"arguments": {
"upload_id": "upl_3JJz6t1o8A5YjX5VpnX27Z"
}
}{
"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
}
]
}{
"type": "https://signatureapi.com/docs/v1/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Could not find Upload upl_3JJz6t1o8A5YjX5VpnX27Z."
}{
"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
}
]
}{
"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 every call can return are in Errors and Authentication.