API v2
This page is for users/developers who wish to use Signify programmatically. This page documents API version 2.
The main difference compared to API version 1 is that users can now create documents with fixed signature locations in POST v2/documents
.
API Documentation
This page is meant for developers, vendors, and IT administrators to understand how to generate the bearer token to access our API to create documents for signing.
Bearer Token & API Key Generation
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. Signify uses bearer authentication.
To generate the token, click on "API Integration" in the navigation bar. From there, click on Generate API key
and copy the token. Use this key to start using Signify's API.

Authentication
Signify's API uses API Key for authentication. User can view and manage API Keys in Signify API Dashboard.
Production secret keys will have production_v1_
version prefix.
Authentication to the API is performed via bearer auth.
Sample CURL request:
curl -X POST "https://app.signify.gov.sg/public/v1/documents" \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: multipart/form-data' \
-F 'documentName=Testing API' \
-F 'recipients=[{"email":"<EMAIL_1>","requiredSignatures":[{"page":1, "positionX":0.1, "positionY":0.2}, {"page":1, "positionX":0.2, "positionY":0.3}], "customMessage": "Please sign on Page 3."},{"email":"<EMAIL_2>","requiredSignatures":[{"page":1, "positionX":0.5, "positionY":0.5}]}]' \
-F 'file=@"<FILE_PATH>"'
All API requests must be made over HTTPS. Calls made over plain HTTP will fail and requests without authentication will also fail.
Errors
Signify API uses conventional API Error to indicate the success or failure of an API request.
200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided.
402 - Request Failed
The parameters were valid but the request failed.
404 - Not Found
The requested resource doesn't exist.
429 - Too Many Requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors
Something went wrong on Signify's end.
{
"message": "Unauthorized"
}
Rate Limits
For all of Signify's APIs, Signify allows up to 100 requests per 10 seconds (subject to change).
Endpoints
Production
https://app.signify.gov.sg/public/
Staging
https://staging.signify.gov.sg/public/
Create Document
POST /v2/documents
Content type
The request must be of type multipart/form-data
.
Signing modes
We support two modes of signing invitation: (1) signing by email and (2) signing by link.
In signing by email, the API caller supplies the email addresses of the signatories, and an email invite is sent out by Signify to the signatories to sign the document.
In signing by link, no email addresses are supplied by the API caller. Signing links are returned to the API caller, who can then redirect their users to the signing link.
The signing mode is specified in the documentMode
property of the request body.
Both signing modes require the API caller to specify the location of the signature placeholders.
Signing by Email
The mandatory fields in request body are:
documentName
- the document namerecipients
- an array of{email: string, requiredSignatures: requiredSignature[], customMessage?: string}
file
- the file binary
The optional fields in the request body are:
documentMode
- For signing by email, you may specify this to beemail
. If not specified, this will default toemail
.redirectUrl
- Signify will redirect to this redirectUrl upon completion of signing (by each email receipient). Only URLs with ahttps
protocol, and a.gov.sg
domain will be accepted.
documentName
string
Yes
Must have at least 4 characters and at most 100 characters. Only the following character set is allowed:
a-zA-Z0-9_\-./() &`;'"
recipients
An array of {email: string, requiredSignatures: requiredSignature[], customMessage?: string}
Yes
Email addresses must be unique.
requiredSignatures
is an array of the requiredSignature
object, which has the type:
{ page: number,
positionX: number,
positionY: number }
page
represents the page that the fixed signature placeholder is locatedpositionX
andpositionY
are numbers between 0 to 1. They represent the location of the fixed signature as a percentage of the total document's width and height respectively. Refer below for instructions on how to retrieve these coordinates.requiredSignature
array has a max length of 20 per email recipient
customMessage
is an optional attribute of 1 to 1000 characters. The message will be sent out as part of the email invitation to the recipient.
file
binary
Yes
Up to 10MB
documentMode
email
literal
No, optional
redirectUrl
string
No, optional
Must have a https
protocol and a .gov.sg
domain
How to obtain positionX and positionY:
One way to obtain positionX
and positionY
is to
Create a document via Signify web https://signify.gov.sg/
Inspect the network call to https://app.signify.gov.sg/api/v1/documents/upload, extract
positionX
andpositionY
from the payloadUse these values in your API call
Sample CURL request:
curl -X POST "https://app.signify.gov.sg/public/v2/documents" \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: multipart/form-data' \
-F 'documentName=Testing API' \
-F 'recipients=[{"email":"<EMAIL_1>","requiredSignatures":[{"page":1, "positionX":0.1, "positionY":0.2}, {"page":1, "positionX":0.2, "positionY":0.3}], "customMessage": "Please sign on Page 3."},{"email":"<EMAIL_2>","requiredSignatures":[{"page":1, "positionX":0.5, "positionY":0.5}]}]' \
-F 'file=@"<FILE_PATH>"'
Returns:
{
"documentId": 20
}
Explanation of fields returned:
documentId
The unique identifier of the document
5
Signing by Link
The mandatory fields in request body are:
documentName
- the document nametotalSignaturesByLink
- a length 1 array of{requiredSignatures: requiredSignature[]}
file
- the file binarydocumentMode
- this must be specified aslink
The optional fields in the request body are:
redirectUrl
- Signify will redirect to this redirectUrl upon completion of signing. Only URLs with ahttps
protocol, and a.gov.sg
domain will be accepted.
documentName
string
Yes
Must have at least 4 characters and at most 100 characters. Only the following character set is allowed:
a-zA-Z0-9_\-./() &`;'"
totalSignaturesByLink
A length 1 array of {requiredSignatures: requiredSignature[]}
Yes
Array must be of length exactly 1
requiredSignature
has the type
{ page: number,
positionX: number,
positionY: number }
page
represents the page that the fixed signature placeholder is locatedpositionX
andpositionY
are numbers between 0 to 1. They represent the location of the fixed signature as a percentage of the total document's width and height respectively. Refer below for instructions on how to retrieve these coordinates.requiredSignature
array has a max length of 20
file
binary
Yes
Up to 10MB
documentMode
link
literal
Yes
redirectUrl
string
No, optional
Must have a https
protocol and a .gov.sg
domain
How to obtain positionX and positionY:
One way to obtain positionX
and positionY
is to
Create a document via Signify web https://signify.gov.sg/
Inspect the network call to https://app.signify.gov.sg/api/v1/documents/upload-link, extract
positionX
andpositionY
from the payloadUse these values in your API call
Sample CURL request:
curl -X POST "https://app.signify.gov.sg/public/v2/documents" \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: multipart/form-data' \
-F 'documentName="Document 1"' \
-F 'totalSignaturesByLink="[{"requiredSignatures": [{"page": 1, "positionX": 0, "positionY": 0}, {"page": 2, "positionX": 0.2, "positionY": 0.3}]} \
-F 'documentMode="link"' \
-F 'file=@"<FILE_PATH>"'
Returns:
{
"documentId": "3",
"signingLinks": [
{
"signingLink": "https://app.signify.gov.sg/documents/sign/01hfk78xjafvn9n8xn084a9rsn",
"totalSignatures": 2
}
]
}
Explanation of fields returned:
documentId
The unique identifier of the document
3
signingLinks
The signing links for this document, in an array.
For each link, signingLink
is the link URL, and totalSignatures
is the number of signatures required for that link, as specified during document creation.
[
{
"signingLink": "https://app.signify.gov.sg/documents/sign/01hfk78xjafvn9n8xn084a9rsn",
"totalSignatures": 3
}
]
Get Documents
GET /v2/documents
Sample CURL request:
curl -X GET "https://app.signify.gov.sg/public/v2/documents" \
-H 'Authorization: Bearer <API_KEY>'
Returns:
[
{
"id": 3,
"documentName": "Document 1",
"expiresAt": "2023-12-19T15:59:59.999Z",
"createdAt": "2023-11-19T07:21:14.065Z",
"status": "draft",
"documentMode": "link"
},
{
"id": 4,
"documentName": "Document 2",
"expiresAt": "2023-12-19T15:59:59.999Z",
"createdAt": "2023-11-19T07:22:21.272Z",
"status": "draft",
"documentMode": "email"
},
{
"id": 5,
"documentName": "Document 3",
"expiresAt": "2023-12-19T15:59:59.999Z",
"createdAt": "2023-11-19T08:23:07.277Z",
"status": "draft",
"documentMode": "email"
}
]
Explanation of fields returned:
id
The unique identifier of the document
6
documentName
The name of the document, as specified during document creation
Document 1
expiresAt
The expiry time of the document, after which it can no longer be accessed
2023-12-19T15:59:59.999Z
createdAt
The creation time of the document
2023-11-19T08:23:20.488Z
status
The status of the document. Either signed
if all signatures required have been completed, or draft
otherwise
signed
documentMode
Type of signing for this document. Either link
if the document is signing by link, or email
otherwise
link
Get Single Document
GET /v2/documents/:id
Sample CURL request:
curl -X GET "https://app.signify.gov.sg/public/v2/documents/6" \
-H 'Authorization: Bearer <API_KEY>'
Returns:
For signing by email:
{
"id": 6,
"documentName": "Document 1",
"documentUrl": "https://app.signify.gov.sg/api/v1/bucket/01hfkatk5tc2mgxq1wefhyn52d",
"expiresAt": "2023-12-19T15:59:59.999Z",
"createdAt": "2023-11-19T08:23:20.488Z",
"status": "draft",
"signingInvitations": [
{
"signatory": "[email protected]",
"totalSignatures": 3,
"status": "draft",
"completedSignatures": []
},
{
"signatory": "[email protected]",
"totalSignatures": 1,
"status": "signed",
"completedSignatures": [
{
"name": "MY NAME",
"timeStamp": "2023-11-19T08:31:36.000Z"
}
]
}
],
"documentMode": "email"
}
For signing by link:
{
"id": 313,
"documentName": "Document 1",
"documentUrl": "https://app.signify.gov.sg/api/v1/bucket/01hfna3nxdxf9nzvev5hw7aaf1",
"expiresAt": "2023-12-20T15:59:59.999Z",
"createdAt": "2023-11-20T02:49:17.105Z",
"status": "signed",
"signingInvitations": [
{
"signingLink": "https://app.signify.gov.sg/documents/sign/01hfna3p1f095s5aqph2dsjr07",
"totalSignatures": 3,
"status": "signed",
"completedSignatures": [
{
"name": "MY NAME",
"timeStamp": "2023-11-20T02:49:37.000Z"
},
{
"name": "MY NAME",
"timeStamp": "2023-11-20T02:50:00.000Z"
},
{
"name": "MY NAME",
"timeStamp": "2023-11-20T02:53:04.000Z"
}
]
}
],
"documentMode": "link"
}
Explanation of fields returned:
id
The unique identifier of the document
6
documentName
The name of the document, as specified during document creation
Document 1
documentUrl
The url where the document file can be retrieved.
⚠️ The document file URL is only guaranteed to be valid for 30 minutes. You should refetch the URL again after that time.
https://app.signify.gov.sg/api/v1/bucket/01hfkatk5tc2mgxq1wefhyn52d
expiresAt
The expiry time of the document, after which it can no longer be accessed
2023-12-19T15:59:59.999Z
createdAt
The creation time of the document
2023-11-19T08:23:20.488Z
status
The status of the document. Either signed
if all signatures required have been completed, or draft
otherwise
signed
signingInvitations
Details of the signing invitations sent out.
signatory
- Email address of the signatory (only for signing by email)
signingLink
- Link for signing (only for signing by link)
totalSignatures
- Number of signatures required from this invite
status
- signed
if all signatures have been collected for this invite, draft
otherwise
completedSignatures
- details of the signatures already collected
{
"signatory": "email2open.gov.sg",
"totalSignatures": 1,
"status": "signed",
"completedSignatures": [
{
"name": "MY NAME",
"timeStamp": "2023-11-19T08:31:36.000Z"
}
]
}
documentMode
Type of signing for this document. Either link
if the document is signing by link, or email
otherwise
link
Delete Document
DELETE /v2/documents/:id
Sample CURL request:
curl -X DELETE "https://app.signify.gov.sg/public/v2/documents/6" \
-H 'Authorization: Bearer <API_KEY>'
Returns:
{
"message": "Document deleted"
}
Last updated
Was this helpful?