Add a document

You can add up to 20 documents to your transaction. We accept PDF, Word and images as input format in a maximum size limit of 25MB for each document (50MB if the Big Files feature is activated on your workspace). The output document (the document that is signed) is always a PDF.

Adding a document to a transaction is a two-step process.

Upload your file to Universign servers

Before you can add the document to your transaction, you must upload your it on our servers. To do so, send a multipart/form-data request to POST /v1/files and pass the document (in PDF, Word or image format) in the file argument:

curl
https://api.universign.com/v1/files \
-F [email protected]

You must send one document per request.

A file ID is returned:

{
  "object" : "file",
  "id" : "file_d0bDo8LgEkEA",
}

Note that we keep the file for 24 hours so you can reuse the file ID during this period.

Add the file ID to your transaction request

To add the file ID to your transaction, send a request to POST /v1/transactions/{transaction_id}/documents and pass the file ID as the document argument.

Note: You must send one request per document.

curl
https://api.universign.com/v1/transactions/tx_aA5g6yzYVYW8/documents \
-d document=file_0Y6rOeYJ6qOBxCZ012yY1LrBeg \
-d name=DocName

You can set other optional arguments:

  • archiving_configuration_id: the ID of the signed documents archiving configuration. To be retrieved from your workspace. For more details about archiving configuration, refer to Archive signed documents.
  • compliance_policy: set to pdfa to force the signing/sealing operation to respect the PDF/A standard. Universign keeps the PDF/A conformance level of the document you upload: for example, a PDF/A-3b document remains PDF/A-3b once signed or sealed. If not set, a PDF/A document will be signed/sealed but will no longer be PDF/A compliant.

  • pdfa_variant: defines how the signature cartridge is rendered when compliance_policy is set to pdfa. Possible values are 1b and 3b. Not setting pdfa_variant is equivalent to setting pdfa_variant=1b. Any other value is ignored.

  • metadata: the metadata of the document, as key-value pairs. For more details, refer to Set document metadata.

Keep your logo transparent with pdfa_variant=3b: PDF/A-1 (ISO 19005-1) forbids transparency. With 1b (or without pdfa_variant), logo and handwritten-signature images are displayed on a white background in the signature cartridge. Transparency is allowed from PDF/A-2 onwards: for PDF/A-2b and PDF/A-3b documents, set pdfa_variant=3b to keep it.

PDF/A is an ISO standardized format (ISO 19005) with strict rules to eliminate anything that could break over time.

PDF/A is commonly required when documents must be archived, exchanged, or legally preserved.

The API returns a document ID. By default, the document name is the imported file name:

{
    "id": "doc_wWz6",
    "name": "myDocument.pdf",
    "updatable": true,
    "deletable": true,
    "fields": []
}

Set document metadata

You can associate metadata (key-value pairs) with each document of a transaction, for example a contract reference, a case number or an identifier from your information system. Metadata are then returned in the API responses and in the transaction archives.

Each document can bear a maximum of 15 metadata. Each metadata key is limited to 20 characters, while the value is limited to 200 characters.

Note that document metadata are not yet included in the transaction search results (text_search) and cannot be edited from the web application yet.

Add metadata when adding a document

To set metadata when you add a document to your transaction, send a request to POST /v1/transactions/{transaction_id}/documents and pass the metadata argument, appended with the metadata key between brackets (for example metadata[contract_ref]):

curl
https://api.universign.com/v1/transactions/tx_aA5g6yzYVYW8/documents \
-d document=file_0Y6rOeYJ6qOBxCZ012yY1LrBeg \
-d name=Contract.pdf \
-d metadata[contract_ref]=C-2026-001 \
-d metadata[case_number]=2026-0042

If you send a full transaction request, pass the metadata in the documents[].metadata object:

"documents" : [{
    "file_id" : "file_0Y6rOeYJ6qOBxCZ012yY1LrBeg",
    "name" : "Contract.pdf",
    "metadata" : {
        "contract_ref" : "C-2026-001",
        "case_number" : "2026-0042"
    },
    "fields" : [ ... ]
  }]

Update document metadata

To update the metadata of a document, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id} and pass the metadata argument. You can do so until the document has been signed or reviewed by a participant.

curl
https://api.universign.com/v1/transactions/tx_aA5g6yzYVYW8/documents/doc_wWz6 \
-d metadata[contract_ref]=C-2026-002 \
-d metadata[case_number]=""

In the above request, the new value of the contract_ref metadata (C-2026-002) replaces the value previously passed (C-2026-001), and the case_number metadata is deleted because its value is empty.

To delete a metadata entry, pass its key with an empty value.

Retrieve document metadata

Document metadata are returned in the documents[].metadata object when you retrieve a transaction or an archived transaction:

"documents" : [ {
    "id" : "doc_wWz6",
    "name" : "Contract.pdf",
    "metadata" : {
      "contract_ref" : "C-2026-001",
      "case_number" : "2026-0042"
    }
  } ]

Errors

The API returns a 400 error in the following cases:

Case error_description
More than 15 metadata entries we can't have more than 15 metadata entries
Metadata key longer than 20 characters metadata keys length can't have more than 20 characters
Metadata value longer than 200 characters metadata values length can't have more than 200 characters
{
    "type": "invalid_request_error",
    "error_description": "we can't have more than 15 metadata entries"
}

For transaction-level metadata, refer to Set transaction metadata.

Import a document from a URL (Full transaction request only)

If you send a full transaction request, you can import a document directly from a URL. This feature allows you to bypass document uploads constraints.

Note that this feature needs to be activated on your workspace. If you wish to activate it, you must contact your account manager at Universign.

You need first to authorize the URL in your workspace. For more details, visit Document URLs.

Then, in your full transaction request, pass the URL in the URL argument. Note that the URL argument must not be passed if the document content or file_id is set.

Important: Make sure the URL leads to the document itself and not to its location.

"documents" : [{
    "url" : "https://getsamplefiles.com/download/pdf/sample-1.pdf",
    "name" : "MyDoc", 
    "fields" : [
        {
      "id" : "field_id_1",
      "name" : "signature field",
      "page" : 1,
      "x" : 150,
      "y" : 275,
      "type" : "signature",
      "consents" : [ "I hereby accept the terms and conditions stated in this document!" ],
      "optional_consents" : [ "I accept to fill a satisfaction form once the signature process is completed!" ] 
    },{
      "id" : "field_id_2",
      "name" : "signature field 2",
      "page" : 1,
      "x" : 175,
      "y" : 200,
      "type" : "signature"
    }]
  }]

Set sender name display
Delete a document
Developer tools
Guides
Services
API reference