{
  "openapi": "3.1.0",
  "info": {
    "title": "SignatureAPI: Uploads",
    "summary": "SignatureAPI is an API-first electronic signature platform.",
    "version": "1.18.0",
    "description": "SignatureAPI is a REST API for sending documents for electronic signature. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes.\n\n### Key concepts\n\nAn **envelope** is the central object. It holds documents and recipients, and manages the signing process from start to finish.\n\nA **document** is a PDF or DOCX file within an envelope. Documents contain **places** — interactive fields like signatures, initials, text inputs, checkboxes, and dropdowns positioned at specific locations.\n\nA **recipient** is a person who receives an envelope. There are three types:\n- **Signer** — signs documents\n- **Approver** — reviews and approves without signing\n- **Preparer** — fills in fields before the signer receives the documents\n\nA **ceremony** is the interactive session where a recipient authenticates and performs their actions. SignatureAPI supports three authentication methods: email link, email code, and custom.\n\nA **deliverable** is the final output — a signed PDF with an audit trail, generated after all recipients complete their actions.\n\nA **sender** is a verified email address that SignatureAPI sends signing requests on behalf of.\n\nAn **upload** is a file stored in SignatureAPI for use as a document source in envelopes.\n\n### HTTP Semantics\n\nWe use HTTP verbs GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.\n\nWe use the following HTTP Status codes for successful responses:\n\n- **200 OK**: Request succeeded for a GET, POST, or PATCH call.\n- **201 Created**: Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource.\n\n### Versioning\n\nWe use [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html):\n\n- We increment Major (the X in X.Y.Z) versions when we make a change that breaks backward compatibility. The current major version is 1.\n- We increment Minor (the Y in X.Y.Z) versions when we add backward compatible features.\n- We increment Patch (the Z in X.Y.Z) versions when we make backward compatible bug fixes or improvements in the documentation.\n\nSignatureAPI considers the following changes to break backward compatibility:\n\n- Removing or renaming fields, arguments, or enum values.\n- Removing endpoints.\n- Changing the type of fields in the response (for example, from string to integer).\n- Adding a new **required** request parameter.\n\nThese are not breaking changes:\n\n- Any additive change, such as adding endpoints, optional arguments, fields, or enum values.\n- Making a required request parameter optional.\n- Making a validation less restrictive.\n- Changes to error responses. _We do not recommend parsing error responses to perform business logic._\n- Changes to the order of fields returned in a response.\n- Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.\n- Adding new event types.\n- Changes in the structure and descriptions in this OpenAPI spec.",
    "contact": {
      "name": "Signature API, Inc.",
      "email": "support@signatureapi.com"
    },
    "termsOfService": "https://signatureapi.com/terms"
  },
  "servers": [
    {
      "description": "SignatureAPI Global Server.",
      "url": "https://api.signatureapi.com/v1"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Uploads",
      "description": "An **upload** is a file stored in SignatureAPI for use as a document source in envelopes. Supports PDF, DOCX, and image files.\n"
    }
  ],
  "paths": {
    "/uploads": {
      "post": {
        "operationId": "CreateUpload",
        "x-audience": "public",
        "tags": [
          "Uploads"
        ],
        "summary": "Create an Upload",
        "description": "Uploads a file to SignatureAPI for use as a document source in an envelope.\n\nThe upload is **temporary** and automatically deleted after **24 hours**. Send the raw file bytes in the request body with the appropriate `Content-Type` header. Maximum file size: **4.5 MB**.\n\nThe response includes a `url` field that can be used anywhere a file URL is accepted, such as in the `document.url` field when adding documents to an envelope.\n\nTo store a **permanent file** that can be reused, use the [Store Upload](/docs/v1/store-upload) endpoint or the file library in your dashboard.\n\n**Accepted media types:**\n\n| Media Type                                                                | Format |\n|---------------------------------------------------------------------------|--------|\n| `application/pdf`                                                         | `pdf`  |\n| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` |\n| `image/png`                                                               | `png`  |\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/pdf": {
              "schema": {
                "type": "string",
                "format": "binary",
                "maxLength": 5242880,
                "title": "PDF File",
                "description": "The raw binary content of the PDF file to upload. Maximum file size: 4.5 MB."
              }
            },
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
              "schema": {
                "type": "string",
                "format": "binary",
                "maxLength": 5242880,
                "title": "DOCX File",
                "description": "The raw binary content of the DOCX file to upload. Maximum file size: 4.5 MB."
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary",
                "maxLength": 5242880,
                "title": "PNG Image",
                "description": "The raw binary content of the PNG image to upload. Maximum file size: 4.5 MB."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The upload was created successfully.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Upload.TemporaryUpload"
                },
                "examples": {
                  "pdf": {
                    "summary": "PDF upload",
                    "value": {
                      "id": "upl_1sAAaVfabdt0esVjmSTmLA",
                      "retention": "temporary",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
                      "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
                      "size": 102400,
                      "format": "pdf",
                      "created_at": "2025-12-30T12:00:00.000Z",
                      "expires_at": "2025-12-31T12:00:00.000Z"
                    }
                  },
                  "docx": {
                    "summary": "DOCX upload",
                    "value": {
                      "id": "upl_3joO7lxE8HVhOZmkCHFCxK",
                      "retention": "temporary",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK",
                      "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
                      "size": 234567,
                      "format": "docx",
                      "created_at": "2025-12-30T12:00:00.000Z",
                      "expires_at": "2025-12-31T12:00:00.000Z"
                    }
                  },
                  "png": {
                    "summary": "PNG upload",
                    "value": {
                      "id": "upl_7kBBcD2eF3gHiJkLmNoPqR",
                      "retention": "temporary",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_7kBBcD2eF3gHiJkLmNoPqR",
                      "sha_256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
                      "size": 51200,
                      "format": "png",
                      "created_at": "2025-12-30T12:00:00.000Z",
                      "expires_at": "2025-12-31T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Shared.ValidationError"
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/uploads/{uploadId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "get": {
        "operationId": "GetUpload",
        "summary": "Retrieve an upload",
        "x-audience": "public",
        "tags": [
          "Uploads"
        ],
        "description": "Retrieves the metadata of an existing upload. Returns details such as the file format, size, SHA-256 hash, and retention type.\n\nThis endpoint returns upload metadata only. The file content cannot be downloaded through the API.\n",
        "responses": {
          "200": {
            "description": "The upload was retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Upload.Upload"
                },
                "examples": {
                  "temporary": {
                    "summary": "Temporary upload",
                    "value": {
                      "id": "upl_1sAAaVfabdt0esVjmSTmLA",
                      "retention": "temporary",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
                      "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
                      "size": 102400,
                      "format": "pdf",
                      "created_at": "2025-12-30T12:00:00.000Z",
                      "expires_at": "2025-12-31T12:00:00.000Z"
                    }
                  },
                  "permanent": {
                    "summary": "Permanent upload",
                    "value": {
                      "id": "upl_3joO7lxE8HVhOZmkCHFCxK",
                      "retention": "permanent",
                      "key": "contract-template-v2",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK",
                      "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
                      "size": 234567,
                      "format": "docx",
                      "created_at": "2025-12-30T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/uploads/{uploadId}/structure": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "get": {
        "operationId": "GetUploadStructure",
        "summary": "Retrieve the structure of an upload",
        "x-audience": "public",
        "tags": [
          "Uploads"
        ],
        "description": "Retrieves the analyzed structure of an uploaded file. The structure includes page dimensions, detected placeholders, and -- for DOCX templates -- detected template fields.\n\nUse this endpoint to verify that placeholders and template fields are correctly detected before creating an envelope.\n\nAvailable for the following file formats:\n\n| Media Type                                                                | Format |\n|---------------------------------------------------------------------------|--------|\n| `application/pdf`                                                         | `pdf`  |\n| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` |\n",
        "responses": {
          "200": {
            "description": "The structure was retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Upload.Structure"
                },
                "examples": {
                  "pdf": {
                    "summary": "PDF document structure",
                    "value": {
                      "format": "pdf",
                      "page_count": 2,
                      "placeholders": [
                        {
                          "key": "signer_signs_here",
                          "page_number": 2,
                          "left": 72,
                          "top": 360,
                          "width": 200,
                          "height": 40,
                          "errors": []
                        }
                      ],
                      "pages": [
                        {
                          "page_number": 1,
                          "width": 612,
                          "height": 792
                        },
                        {
                          "page_number": 2,
                          "width": 612,
                          "height": 792
                        }
                      ]
                    }
                  },
                  "docx": {
                    "summary": "DOCX template structure",
                    "value": {
                      "format": "docx",
                      "page_count": 3,
                      "placeholders": [
                        {
                          "key": "signer_signs_here",
                          "page_number": 3,
                          "left": 72,
                          "top": 500,
                          "width": 200,
                          "height": 40,
                          "errors": []
                        }
                      ],
                      "fields": [
                        {
                          "key": "policyholder.name",
                          "page_number": 1,
                          "left": 100.1,
                          "top": 200.5,
                          "width": 150,
                          "height": 20.1,
                          "errors": []
                        },
                        {
                          "key": "policy.number",
                          "page_number": 1,
                          "left": 100.1,
                          "top": 230.5,
                          "width": 150,
                          "height": 20.1,
                          "errors": []
                        }
                      ],
                      "pages": [
                        {
                          "page_number": 1,
                          "width": 612,
                          "height": 792
                        },
                        {
                          "page_number": 2,
                          "width": 612,
                          "height": 792
                        },
                        {
                          "page_number": 3,
                          "width": 612,
                          "height": 792
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/uploads/{uploadId}/store": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "post": {
        "operationId": "StoreUpload",
        "summary": "Store an upload",
        "description": "Converts a temporary upload into a permanent upload. The file is moved to permanent storage and will no longer expire. A unique `key` is required to identify the permanent upload.\n",
        "x-audience": "public",
        "tags": [
          "Uploads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "$ref": "#/components/schemas/Upload.Key"
                  }
                },
                "required": [
                  "key"
                ]
              },
              "examples": {
                "store": {
                  "summary": "Store with a key",
                  "value": {
                    "key": "contract-template-v2"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The upload was stored successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Upload.PermanentUpload"
                },
                "examples": {
                  "stored": {
                    "summary": "Upload stored permanently",
                    "value": {
                      "id": "upl_1sAAaVfabdt0esVjmSTmLA",
                      "retention": "permanent",
                      "key": "contract-template-v2",
                      "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
                      "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
                      "size": 102400,
                      "format": "pdf",
                      "created_at": "2025-12-30T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Shared.ValidationError"
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Authentication to the API is performed via an API key in the `X-API-Key` header.\n\nYour API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.\n"
      }
    },
    "schemas": {
      "Shared.Problem": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "object",
        "description": "An error response following the RFC 9457 Problem Details format. The API returns this object with a `application/problem+json` content type when a request fails. Use the `type` URL to identify the error programmatically and the `detail` field to understand what went wrong.\n",
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "description": "A URL that identifies the problem type. Points to documentation explaining the error.",
            "format": "uri",
            "example": "https://signatureapi.com/docs/v1/errors/invalid-api-key"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.",
            "example": "Invalid API Key"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code for this error. Matches the status code in the HTTP response.",
            "minimum": 100,
            "maximum": 599,
            "example": 401
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem.",
            "example": "Please provide a valid API key in the X-API-Key header."
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ]
      },
      "Shared.ValidationProblem": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "description": "A validation error response following the RFC 9457 Problem Details format. The API returns this object with HTTP status 422 when a request body fails validation. The `errors` array lists each field-level problem so you can fix them all in one pass.\n",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URL pointing to the validation error documentation. Always `https://signatureapi.com/docs/v1/errors/validation-error`.",
            "format": "uri",
            "const": "https://signatureapi.com/docs/v1/errors/validation-error",
            "example": "https://signatureapi.com/docs/v1/errors/validation-error"
          },
          "title": {
            "type": "string",
            "description": "A short summary of the problem type. Always `Validation Error`.",
            "const": "Validation Error",
            "example": "Validation Error"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code. Always `422` for validation errors.",
            "const": 422,
            "example": 422
          },
          "errors": {
            "type": "array",
            "description": "A list of human-readable messages describing each validation failure.",
            "items": {
              "type": "string"
            },
            "example": [
              "documents[0].url protocol must be HTTPS",
              "recipients[0].email must be a valid email address"
            ]
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "errors"
        ]
      },
      "Upload.Id": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "string",
        "title": "Upload ID",
        "description": "The unique identifier of the upload.",
        "example": "upl_1sAAaVfabdt0esVjmSTmLA"
      },
      "Upload.Retention": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Retention",
        "description": "The retention type of the upload.\n\n- `temporary` -- The file is automatically deleted after 24 hours. Created through the API.\n- `permanent` -- The file is stored indefinitely. Created through the dashboard library.\n",
        "example": "temporary",
        "type": "string",
        "enum": [
          "temporary",
          "permanent"
        ]
      },
      "Upload.Url": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "URL",
        "description": "A URL used to reference the uploaded file.\n\nThis internal URL can be used as input in other fields, like `document.url`.\n\nThe file's content cannot be retrieved directly via this URL.\n",
        "type": "string",
        "format": "uri",
        "example": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK"
      },
      "Upload.Sha256": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "SHA-256 Hash",
        "description": "The SHA-256 hash of the uploaded file in hexadecimal format.",
        "type": "string",
        "example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      },
      "Upload.Size": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Size",
        "description": "The size of the uploaded file in bytes. Maximum file size: 4.5 MB (4,500,000 bytes).",
        "type": "integer",
        "example": 102400
      },
      "Upload.Format": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "string",
        "title": "Format",
        "description": "The file format of the upload.\n\n- `pdf` -- A PDF file (`application/pdf`).\n- `docx` -- A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`).\n- `png` -- A PNG image (`image/png`).\n",
        "example": "pdf",
        "enum": [
          "pdf",
          "docx",
          "png"
        ]
      },
      "Upload.CreatedAt": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Created At",
        "description": "The date and time when the upload was created, in ISO 8601 format.",
        "type": "string",
        "format": "date-time",
        "example": "2025-12-31T00:00:00.000Z"
      },
      "Upload.ExpiresAt": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Expires At",
        "description": "The date and time when the temporary upload expires and is automatically deleted, in ISO 8601 format. Only present on temporary uploads. The expiration is 24 hours after creation.\n",
        "type": "string",
        "format": "date-time",
        "example": "2025-12-31T00:00:00.000Z"
      },
      "Upload.TemporaryUpload": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Temporary Upload",
        "description": "A temporary upload stored in SignatureAPI for 24 hours. Temporary uploads are created through the API and automatically deleted when they expire. Best for one-time use when creating an envelope.\n",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Upload.Id"
          },
          "retention": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Upload.Retention"
              },
              {
                "const": "temporary"
              }
            ]
          },
          "url": {
            "$ref": "#/components/schemas/Upload.Url"
          },
          "sha_256": {
            "$ref": "#/components/schemas/Upload.Sha256"
          },
          "size": {
            "$ref": "#/components/schemas/Upload.Size"
          },
          "format": {
            "$ref": "#/components/schemas/Upload.Format"
          },
          "created_at": {
            "$ref": "#/components/schemas/Upload.CreatedAt"
          },
          "expires_at": {
            "$ref": "#/components/schemas/Upload.ExpiresAt"
          }
        },
        "required": [
          "id",
          "retention",
          "url",
          "sha_256",
          "size",
          "format",
          "created_at",
          "expires_at"
        ]
      },
      "Upload.Key": {
        "x-schema-role": "property",
        "x-schema-direction": "any",
        "title": "Upload Key",
        "description": "A unique key that identifies the permanent upload within your account. Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters.\n",
        "pattern": "^[a-z0-9_-]+$",
        "maxLength": 100,
        "type": "string",
        "example": "contract-template-v2"
      },
      "Upload.PermanentUpload": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Permanent Upload",
        "description": "A permanent upload stored in SignatureAPI indefinitely. Permanent uploads are created through the dashboard library and can be reused across multiple envelopes. Each permanent upload has a unique `key` for identification.\n",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Upload.Id"
          },
          "retention": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Upload.Retention"
              },
              {
                "const": "permanent"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Upload.Key"
          },
          "url": {
            "$ref": "#/components/schemas/Upload.Url"
          },
          "sha_256": {
            "$ref": "#/components/schemas/Upload.Sha256"
          },
          "size": {
            "$ref": "#/components/schemas/Upload.Size"
          },
          "format": {
            "$ref": "#/components/schemas/Upload.Format"
          },
          "created_at": {
            "$ref": "#/components/schemas/Upload.CreatedAt"
          }
        },
        "required": [
          "id",
          "retention",
          "key",
          "url",
          "sha_256",
          "size",
          "format",
          "created_at"
        ]
      },
      "Upload.Upload": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "description": "An **upload** is a file stored in SignatureAPI that can be used as a document source in an envelope.\n\nUploads support two file formats: **PDF** and **DOCX**. Maximum file size: 4.5 MB.\n\n### Retention\n\nUploads have one of two retention types:\n\n- **Temporary** -- Created through the API. Automatically deleted after 24 hours. Best for one-time use.\n- **Permanent** -- Created through the dashboard library. Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`.\n\n### Usage\n\nAfter uploading a file, use the returned `url` value as the document source when creating an envelope. This URL is an internal reference and cannot be used to download the file directly.\n\n### Structure\n\nUse the **Get Upload Structure** endpoint to inspect the internal structure of an uploaded file. The structure includes page dimensions, detected **placeholders**, and -- for DOCX templates -- detected **template fields**.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Upload.TemporaryUpload"
          },
          {
            "$ref": "#/components/schemas/Upload.PermanentUpload"
          }
        ],
        "discriminator": {
          "propertyName": "retention",
          "mapping": {
            "permanent": "#/components/schemas/Upload.PermanentUpload",
            "temporary": "#/components/schemas/Upload.TemporaryUpload"
          }
        }
      },
      "Upload.PageCount": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "integer",
        "title": "Page Count",
        "description": "The total number of pages in the uploaded file.",
        "example": 3
      },
      "Upload.PlaceholderKey": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Key",
        "description": "The key of the placeholder, extracted from the `[[key]]` syntax in the document. Must match the `key` of a place defined in the envelope.\n",
        "type": "string",
        "example": "signer_signs_here"
      },
      "Upload.PlaceholderPageNumber": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Page Number",
        "description": "The page number where the placeholder is located.",
        "type": "integer",
        "example": 3
      },
      "Upload.PlaceholderLeft": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Left Distance",
        "description": "The distance in points (1/72 of an inch) from the left edge of the page to the left edge of the placeholder.\n",
        "type": "number",
        "example": 100.1
      },
      "Upload.PlaceholderTop": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Top Distance",
        "description": "The distance in points (1/72 of an inch) from the top edge of the page to the bottom edge of the placeholder.\n",
        "type": "number",
        "example": 100.1
      },
      "Upload.PlaceholderWidth": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Width",
        "description": "The width in points (1/72 of an inch) of the placeholder.",
        "type": "number",
        "example": 100.1
      },
      "Upload.PlaceholderHeight": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Height",
        "description": "The height in points (1/72 of an inch) of the placeholder.",
        "type": "number",
        "example": 20.1
      },
      "Upload.PlaceholderErrors": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholder Errors",
        "description": "Validation errors detected for the placeholder. An empty array means the placeholder is valid.\n",
        "type": "array",
        "items": {
          "type": "string"
        },
        "example": [
          "Placeholder key has an invalid format."
        ]
      },
      "Upload.Placeholder": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Placeholder",
        "description": "A placeholder detected in an uploaded document. Placeholders use the `[[key]]` syntax and mark positions where signature fields and other interactive elements appear. The placeholder key must match the `key` of a place defined in the envelope.\n",
        "type": "object",
        "properties": {
          "key": {
            "$ref": "#/components/schemas/Upload.PlaceholderKey"
          },
          "page_number": {
            "$ref": "#/components/schemas/Upload.PlaceholderPageNumber"
          },
          "left": {
            "$ref": "#/components/schemas/Upload.PlaceholderLeft"
          },
          "top": {
            "$ref": "#/components/schemas/Upload.PlaceholderTop"
          },
          "width": {
            "$ref": "#/components/schemas/Upload.PlaceholderWidth"
          },
          "height": {
            "$ref": "#/components/schemas/Upload.PlaceholderHeight"
          },
          "errors": {
            "$ref": "#/components/schemas/Upload.PlaceholderErrors"
          }
        },
        "required": [
          "key",
          "page_number",
          "left",
          "top",
          "width",
          "height",
          "errors"
        ]
      },
      "Upload.Placeholders": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Placeholders",
        "description": "The placeholders detected in the document. Placeholders use the `[[key]]` syntax and mark positions where signature fields and other interactive elements appear during signing.\n",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Upload.Placeholder"
        }
      },
      "Upload.PageNumber": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "integer",
        "title": "Page Number",
        "description": "The page number, starting from 1.",
        "example": 1
      },
      "Upload.PageHeight": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "number",
        "title": "Page Height",
        "description": "The height of the page in points (1/72 of an inch)",
        "example": 792
      },
      "Upload.PageWidth": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "number",
        "title": "Page Width",
        "description": "The width of the page in points (1/72 of an inch)",
        "example": 612
      },
      "Upload.Page": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Page",
        "description": "A page in the uploaded document, with its dimensions in points.",
        "type": "object",
        "properties": {
          "page_number": {
            "$ref": "#/components/schemas/Upload.PageNumber"
          },
          "height": {
            "$ref": "#/components/schemas/Upload.PageHeight"
          },
          "width": {
            "$ref": "#/components/schemas/Upload.PageWidth"
          }
        },
        "required": [
          "page_number",
          "height",
          "width"
        ]
      },
      "Upload.Pages": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Pages",
        "description": "The pages in the uploaded document, including dimensions for each page.",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Upload.Page"
        }
      },
      "Upload.PdfDocumentStructure": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "PDF Document Structure",
        "description": "The analyzed structure of a PDF upload. Includes page dimensions and detected placeholders. PDF documents support placeholders (`[[key]]`) for positioning signature fields and other interactive elements.\n",
        "type": "object",
        "properties": {
          "format": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Upload.Format"
              },
              {
                "const": "pdf"
              }
            ]
          },
          "page_count": {
            "$ref": "#/components/schemas/Upload.PageCount"
          },
          "placeholders": {
            "$ref": "#/components/schemas/Upload.Placeholders"
          },
          "pages": {
            "$ref": "#/components/schemas/Upload.Pages"
          }
        },
        "required": [
          "format",
          "page_count",
          "placeholders",
          "pages"
        ],
        "additionalProperties": false
      },
      "Upload.FieldKey": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Key",
        "description": "The key of the template field, extracted from the `{{key}}` syntax in the DOCX template. Supports dot notation for nested data (e.g., `person.name`).\n",
        "type": "string",
        "example": "policyholder.name"
      },
      "Upload.FieldPageNumber": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Page Number",
        "description": "The page number where the template field is located.",
        "type": "integer",
        "example": 3
      },
      "Upload.FieldLeft": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Left Distance",
        "description": "The distance in points (1/72 of an inch) from the left edge of the page to the left edge of the template field.\n",
        "type": "number",
        "example": 100.1
      },
      "Upload.FieldTop": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Top Distance",
        "description": "The distance in points (1/72 of an inch) from the top edge of the page to the bottom edge of the template field.\n",
        "type": "number",
        "example": 100.1
      },
      "Upload.FieldWidth": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Width",
        "description": "The width in points (1/72 of an inch) of the template field.",
        "type": "number",
        "example": 100.1
      },
      "Upload.FieldHeight": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Height",
        "description": "The height in points (1/72 of an inch) of the template field.",
        "type": "number",
        "example": 20.1
      },
      "Upload.FieldErrors": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Field Errors",
        "description": "Validation errors detected for the template field. An empty array means the field is valid.\n",
        "type": "array",
        "items": {
          "type": "string"
        },
        "example": [
          "Field name has an invalid format."
        ]
      },
      "Upload.Field": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Template Field",
        "description": "A template field detected in a DOCX template. Template fields use the `{{key}}` syntax and are replaced with data values when the document is generated. For example, `{{name}}` is replaced with the value provided in the document's `data` field.\n",
        "type": "object",
        "properties": {
          "key": {
            "$ref": "#/components/schemas/Upload.FieldKey"
          },
          "page_number": {
            "$ref": "#/components/schemas/Upload.FieldPageNumber"
          },
          "left": {
            "$ref": "#/components/schemas/Upload.FieldLeft"
          },
          "top": {
            "$ref": "#/components/schemas/Upload.FieldTop"
          },
          "width": {
            "$ref": "#/components/schemas/Upload.FieldWidth"
          },
          "height": {
            "$ref": "#/components/schemas/Upload.FieldHeight"
          },
          "errors": {
            "$ref": "#/components/schemas/Upload.FieldErrors"
          }
        },
        "required": [
          "key",
          "page_number",
          "left",
          "top",
          "width",
          "height",
          "errors"
        ]
      },
      "Upload.Fields": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Template Fields",
        "description": "The template fields detected in the DOCX document. Template fields use the `{{key}}` syntax and are replaced with values from the document's `data` field when the document is generated. Only present for DOCX uploads.\n",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Upload.Field"
        }
      },
      "Upload.DocxDocumentStructure": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "DOCX Document Structure",
        "description": "The analyzed structure of a DOCX upload. Includes page dimensions, detected placeholders, and detected template fields. DOCX documents support both placeholders (`[[key]]`) for positioning interactive elements and template fields (`{{key}}`) for dynamic data insertion.\n",
        "type": "object",
        "properties": {
          "format": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Upload.Format"
              },
              {
                "const": "docx"
              }
            ]
          },
          "page_count": {
            "$ref": "#/components/schemas/Upload.PageCount"
          },
          "placeholders": {
            "$ref": "#/components/schemas/Upload.Placeholders"
          },
          "fields": {
            "$ref": "#/components/schemas/Upload.Fields"
          },
          "pages": {
            "$ref": "#/components/schemas/Upload.Pages"
          }
        },
        "required": [
          "format",
          "page_count",
          "placeholders",
          "fields",
          "pages"
        ]
      },
      "Upload.Structure": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Structure",
        "description": "The analyzed structure of an uploaded file. Includes page dimensions, detected placeholders, and -- for DOCX templates -- detected template fields. Use this to verify that placeholders and fields are correctly positioned before creating an envelope.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Upload.PdfDocumentStructure"
          },
          {
            "$ref": "#/components/schemas/Upload.DocxDocumentStructure"
          }
        ],
        "discriminator": {
          "propertyName": "format",
          "mapping": {
            "pdf": "#/components/schemas/Upload.PdfDocumentStructure",
            "docx": "#/components/schemas/Upload.DocxDocumentStructure"
          }
        }
      }
    },
    "parameters": {
      "UploadId": {
        "name": "uploadId",
        "in": "path",
        "description": "The unique identifier of an upload.",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Upload.Id"
        }
      }
    },
    "responses": {
      "Shared.ClientError": {
        "description": "The request cannot be processed due to an issue on the client's side. This may include invalid request format, insufficient permissions, or requesting non-existent resources. The client should review and correct the request.\n\nThis error covers HTTP status codes in the 400 to 499 range. The most common are:\n\n- 400 Bad Request (`bad-request`: the request body is not valid JSON)\n- 401 Unauthorized\n- 402 Payment Required (`live-mode-paused`: live API access is paused because an invoice is unpaid; test keys keep working)\n- 403 Forbidden\n- 409 Conflict\n- 410 Gone\n- 404 Not Found\n- 413 Request Too Large (`request-too-large`: a JSON request body exceeds 1500 KiB, a form-encoded body exceeds 100 KiB, or a form-encoded body has too many parameters)\n- 415 Unsupported Media Type (`unsupported-media-type`: the request body's charset or content encoding is not supported)\n- 422 Unprocessable Content.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.Problem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/api-key-required",
              "title": "The API Key is required",
              "status": 401,
              "detail": "A valid API key is required in the X-API-Key header of all requests."
            }
          }
        }
      },
      "Shared.ServerError": {
        "description": "The request cannot be processed due to an issue on the server's side. The client can retry the request in a few minutes, or contact support if the error persists.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.Problem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/server-error",
              "title": "Internal Server Error",
              "status": 500,
              "detail": "There was a problem in our server and your request was not fulfilled. Try again later. If the error persists, please contact support.\n"
            }
          }
        }
      },
      "Shared.ValidationError": {
        "description": "The request cannot be processed due to validation errors. This typically involves issues like missing required fields, invalid data formats, or value constraints not being met.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.ValidationProblem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/validation-error",
              "title": "Validation Error",
              "status": 422,
              "errors": [
                "The title is required",
                "The sender.email is not a valid email address",
                "The value of recipients[0].key is too long"
              ]
            }
          }
        }
      }
    },
    "headers": {
      "Location": {
        "required": true,
        "description": "The URL of the created resource",
        "schema": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}
