Upload Documents

Before creating a signing request, upload the PDF document to SignumEra and use the returned upload_id when creating the signing request.

The upload endpoint accepts the PDF as the raw HTTP request body. Do not send the document as multipart/form-data.

Upload a PDF

POST /api/v1/uploads

Required Scope

signing.create

Headers

Header	Required	Description
`Authorization`	Yes	OAuth Bearer access token.
`Content-Type`	Yes	Must be exactly `application/pdf`.
`Accept`	Recommended	`application/json`
`X-Filename`	No	Original document filename. If omitted, `document.pdf` is used.

Maximum File Size

PDF uploads are limited to 50 MiB.

Example

curl -X POST \
  "https://api.signumera.com/api/v1/uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: agreement.pdf" \
  --data-binary "@agreement.pdf"

Success

A successful upload returns HTTP 201 Created.

{
    "upload_id": "upl_EXAMPLE",
    "filename": "agreement.pdf",
    "sha256": "DOCUMENT_SHA256",
    "size_bytes": 245760,
    "expires_in_hours": 24
}

Field	Description
`upload_id`	Temporary SignumEra upload identifier. Valid upload identifiers begin with `upl_`.
`filename`	Normalized filename stored with the uploaded PDF.
`sha256`	SHA-256 digest of the uploaded PDF.
`size_bytes`	Size of the uploaded document in bytes.
`expires_in_hours`	Number of hours the temporary upload remains available for use in a signing request.

Create the signing request before the temporary upload expires. Use the returned upload_id as document.upload_id.

Use the Upload ID

The returned identifier becomes document.upload_id when creating a signing request:

{
    "external_reference": "contract-2026-001",
    "transaction_type": "agreement",

    "document": {
        "upload_id": "UPLOAD_ID"
    },

    "recipients": [
        {
            "participant_type": "signer",
            "role": "Signer",
            "name": "Jane Smith",
            "email": "jane@example.com"
        }
    ],

    "ceremony": {
        "mode": "YOUR_CEREMONY_MODE",
        "meeting_provider": "YOUR_MEETING_PROVIDER"
    },

    "evidence_level": "YOUR_EVIDENCE_LEVEL"
}

Filename Handling

The optional X-Filename value is normalized by SignumEra before the document is submitted to the signing service.

Directory components are removed.
The filename is converted to ASCII.
Unsupported characters are replaced.
The filename is limited to 180 characters.
If the name does not end in .pdf, SignumEra adds the extension.

Errors

HTTP	Code	Description
415	`invalid_content_type`	Content-Type was not `application/pdf`.
422	`missing_pdf`	The request body was empty.
413	`pdf_too_large`	The PDF exceeds the 50 MiB limit.
422	`invalid_pdf`	The request body does not contain a valid PDF header.
503	`upstream_unavailable`	The SignumEra document upload service is temporarily unavailable.

Example Error

{
    "error": {
        "code": "invalid_content_type",
        "message": "Content-Type must be application/pdf."
    }
}