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 topdfato 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 whencompliance_policyis set topdfa. Possible values are1band3b. Not settingpdfa_variantis equivalent to settingpdfa_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"
}]
}]
