API v2

This page is for users/developers who wish to use Signify programmatically. This page documents API version 2.

PreviousAPI Guide NextAPI v1 (deprecated)

Last updated 6 months ago

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.

Keep the bearer token safe: You should not share the bearer token with anyone. Use services like 1Password to store it.

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.

Status Codes

Description

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

Environment

Endpoint

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 name
recipients - 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 be email. If not specified, this will default to email.
redirectUrl - Signify will redirect to this redirectUrl upon completion of signing (by each email receipient). Only URLs with a https protocol, and a .gov.sg domain will be accepted.

Property

Type

Required?

Restrictions

documentName

string

Yes

Must have at least 4 characters and at most 100 characters. Only the following character set is allowed:

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 represents the page that the fixed signature placeholder is located
positionX and positionY 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 and positionY from the payload
Use 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:

Field returned

What it means

Example

documentId

The unique identifier of the document

Signing by Link

The mandatory fields in request body are:

documentName - the document name
totalSignaturesByLink - a length 1 array of {requiredSignatures: requiredSignature[]}
file - the file binary
documentMode - this must be specified as link

The optional fields in the request body are:

redirectUrl - Signify will redirect to this redirectUrl upon completion of signing. Only URLs with a https protocol, and a .gov.sg domain will be accepted.

Property

Type

Required?

Restrictions

documentName

string

Yes

Must have at least 4 characters and at most 100 characters. Only the following character set is allowed:

totalSignaturesByLink

A length 1 array of {requiredSignatures: requiredSignature[]}

Yes

Array must be of length exactly 1

requiredSignature has the type

page represents the page that the fixed signature placeholder is located
positionX and positionY 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 and positionY from the payload
Use 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:

Field returned

What it means

Example

documentId

The unique identifier of the document

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.

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:

Field returned

What it means

Example

id

The unique identifier of the document

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": "email1@open.gov.sg",
            "totalSignatures": 3,
            "status": "draft",
            "completedSignatures": []
        },
        {
            "signatory": "email2@open.gov.sg",
            "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:

Field returned

What it means

Example

id

The unique identifier of the document

documentName

The name of the document, as specified during document creation

Document 1

documentUrl

The url where the document file can be retrieved.

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

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"
}