API integration pre-requisites
You will need an API key to authenticate most requests made to the Universign API. Only users with administrator or integrator rights can create API keys.
Create your API key
From the Developer menu on the web application, navigate to the API keys section and click Create an API key.
1. Name your API key explicitely. It will be easier for you to identify which API can be deleted, for example.
2. Copy your API key and store it in a secure place on your side. For security reasons, Universign does not store API keys in clear text.
3. Create your key.
Authenticate your request
Once you created your API key, you are ready to authenticate your request. Add it to the request header as the value of the username followed by a colon: -u your_API_key: (the password field can be left empty).
Alternatively, you can authenticate via bearer auth: -H "Authorization: Bearer your_API_key"
Authentication errors
If you don’t provide an API key or provide an invalid one when authentication is required, you will receive a 401 - Unauthorized response.
If the API key you provided does not grant you access to the resource, you will receive a 403 - Forbidden response.
Send your first document to be signed
1. Create a transaction
Create a draft transaction by sending a request to the endpoint POST /v1/transactions.
curl
https://api.universign.com/v1/transactions
The API returns a transaction object including an id:
{
"object": "transaction",
"id": "tx_AWo949MOq0JE",
"folder_id": "fol_MJQbbKe5PV7d",
"created_at": "2022-10-18T07:34:58Z",
"duration": 20160,
"name": "tx_AWo949MOq0JE",
"folder_name": "My folder",
"stalled": false,
"language": "fr",
"creator": {
"workspace_name": "My company",
"api_key_name": "My API key"
},
"state": "draft",
"participants": [],
"watchers": [],
"sealers": [],
"documents": [],
"instructions": {
"signatures": [],
"reviews": [],
"captures": [],
"sequencing": [],
"editions": []
},
"actions": [],
"metadata": {},
"progress_value": 0,
"ongoing_conversation": false,
"has_unread_message": false,
"origin": "API",
"carbon_copies": [],
"uploads": [],
"max_expiry": "180_days",
"private": false
}
2. Add a document
Adding a document to a transaction is a two-step process.
2.1. Upload your file to Universign servers
Before you can add the document to your transaction, you must upload 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]
A file ID is returned:
{
"object" : "file",
"id" : "file_d0bDo8LgEkEA",
}
2.2. 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 via the document argument.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents \
-d document=file_d0bDo8LgEkEA \
You are returned a document ID in the API response. The document name is the file name by default:
{
"id": "doc_wWz6",
"name": "myDocument.pdf",
"updatable": true,
"deletable": true,
"fields": []
}
3. Add a signature field to the document
To add a signature field to your transaction, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass signature as field type argument:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=signature
4. Assign a signer to the field
To assign a signer, you must link the signature field you just created to the signer’s email. To do so, send a request to POST /v1/transactions/{transaction_id}/signatures and pass the field and signer arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d [email protected] \
-d field=fld_5XoG
The API returns:
{
"id": "fld_5XoG",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": true
}
5. Activate signer notification (optional)
When the transaction is created by API, no invitation is sent to the signer by default. If you want the signer to receive an invitation to access the document, send a request to POST /v1/transactions/{transaction_id}/participants and pass the signer email in the email argument and 0 in the schedule argument. (visit add invitation message for more details).
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/participants \
-d [email protected] \
-d schedule=[0]
Note that the invitation will not be sent as long as your transaction is in draft.
6. Start your transaction
You are ready to send your first transaction. To do so, send a request to POST /v1/transactions/{transaction_id}/start:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/start
A transaction object is returned, with a started state.
{
"object": "transaction",
"id": "tx_AWo949MOq0JE",
"folder_id": "fol_DGX2qbq6yGmm",
"created_at": "2022-10-19T10:23:07Z",
"started_at": "2022-10-19T10:31:41Z",
"expires_at": "2022-11-02T10:31:41Z",
"name": "tx_k1b29GMrJJzW",
"folder_name": "Default folder",
"stalled": false,
"language": "fr",
"creator": {
"workspace_name": "WorkspaceName",
"api_key_name": "MyAPIKey"
},
"state": "started",
"participants": [
{
"email": "[email protected]",
"min_signature_level": "level1",
"schedule": [
0
],
"ongoing_conversation": false,
"has_unread_message": false,
"state": "open"
}
],
"watchers": [],
"sealers": [],
"documents": [
{
"id": "doc_wWz6",
"name": "DocumentName.pdf",
"updatable": true,
"deletable": false,
"fields": [
{
"id": "fld_5XoG",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": false
}
]
}
],
"instructions": {
"signatures": [
{
"signer": "[email protected]",
"field": "fld_5XoG"
}
],
"reviews": [],
"captures": [],
"sequencing": [],
"editions": []
},
"actions": [
{
"id": "act_vP4399Kob9PWE",
"actor": "[email protected]",
"state": "open",
"url": "https://apps.trunk.universign.net/npds/act_vP4399Kob9PWE",
"tasks": [
{
"type": "signature",
"state": "todo",
"field": "fld_5XoG"
}
],
"stalled": false
}
],
"metadata": {},
"progress_value": 0,
"ongoing_conversation": false,
"has_unread_message": false,
"origin": "API",
"carbon_copies": [],
"uploads": [],
"private": false
}
Your transaction is now live: the signer instantly receives an email with a link to access the document to be signed.
Note that you can create and start a fully configured transaction using one single request. For more details, visit Full transaction request.
