Initiate Sign Request

This endpoint allows RP to initiate a signing session by sending the raw PDF document. The service processes the document to set up a signing transaction and returns a unique sign request identifier along with a signing URL to redirect users to in order for them to perform the signing.

Each signing session has a validity of 30 mins. RPs should only initiate a request when the application is ready to redirect the user to the Sign portal to perform the signing.

All signing sessions must be initiated via the Singpass button and not through providing any redirect links directly to the user.

Path

POST /sign-requests

Headers

Name	Value
Content-Type	application/octet-stream
Authorization	<token>

Authorization token

RPs should sign the signature parameter into a JWT token as authorization token.

• Token Type: Standard JWT (JSON Web Token)

• Payload:

  • x & y: Coordinates for placing the signature. The values should be ≥ 0 and <1, with a maximum precision of four decimal places. See detailed explaination in How to set signing coordinates

  • page: The page number for placing the signature. Starting from 1.

  • doc_name: The name of the document. This will be shown to the user.

  • client_id: Your application's registered client ID.

  • jti: Standard JWT ID, a unique identifier for the JWT, must be a UUID.

  • iat & exp: Standard Issued At / Expiration timestamp of JWT. Must issued within 2 minutes.

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ5YmUyYzU5LThlN2QtNGJiMS1iZTcwLTA4YWExMTcxNWI0ZiJ9.eyJjbGllbnRfaWQiOiI5UmdHQ0hlOFgxIiwiZG9jX25hbWUiOiJ0ZXN0LnBkZiIsIngiOjEsInkiOjEsInBhZ2UiOjEsImlhdCI6MTc0NzM3NzQ5MiwianRpIjoiZWEzOTI3ZGMtNmUxNy00YzkyLWJjZmUtNjU3NTE4NTg5YWM2In0.Hibgb47lL9cXpRzH0hjSRg027bZHBSY5lsGXH9MKukHyDbUi4d6hMcTVu_xYF6dJXPizFmRceuxaQVKM_h1pYA

You can use the free tool https://jwt.io/ to verify if your token is signed properly.

Body

Raw binary PDF content

PDF Requirements

• PDF must be less than 10 MB in size.

• PDF must be unencrypted.

• If the PDF contains existing signature(s):

  • These signatures should fulfil the requirements of a PAdES signature (minimally B-T). Note: Signatures created with Sign will automatically fulfil these requirements

  • These signatures should not overlap with the x-y coordinates given.

Response

Created (201)

The signing URL will bring the signer to the Sign Portal where they will perform the signing.

{
  "request_id": "signv3-01961944-5491-785a-baf2-edea694ae61a",
  "signing_url": "https://staging.sign.singpass.gov.sg/?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNpZ24tc3RnLTAxIn0.eyJyZXF1ZXN0X2lkIjoic2lnbnYzLTAxOTYxOTQ0LTU0OTEtNzg1YS1iYWYyLWVkZWE2OTRhZTYxYSIsImlhdCI6MTc0NDE4MDYzMCwiZXhwIjoxNzQ0MTgyNDMwfQ.UGBmPO2IHUKxyMO9ZjpGt_NuhHqbBTz2IuFmYcHFzi0slw3K1V-XpIfVqW8ua3PGoWf52jNPBH2lkPhcz69r6A&request_id=signv3-01961944-5491-785a-baf2-edea694ae61a",
  "exchange_code": "37994734-1d76-4d27-b5f0-96dd1504cf67"
}

Invalid File Error (400)

There may be a few scenarios under which you will receive a 400 error:

• CONTENT_TOO_LARGE: File size has exceeded 10 MB

• BAD_SIGN_LOCATION: The signature coordinates could be out of bounds, overlapping other forms or in a page that is non existent.

• INVALID_PDF: The PDF file in the request may be corrupted or set with MDP permissions that restrict further signing.

• CLIENT_SIDE_ERROR: A catch-all error for bad input values (for e.g. a number when a string is expected)

{
  "error": "BAD_SIGN_LOCATION",
  "error_description": "Signature field is out of bounds",
  "id": "ca21bb57-8255-46f0-b2f4-80613768ea6e",
  "trace_id": "7755321139078968799"
}

Auth Token Error (401)

{
  "error": "UNAUTHORIZED",
  "error_description": "Unauthorized.",
  "error_details": "JWT validation failed",
  "id": "ca21bb57-8255-46f0-b2f4-80613768ea6e",
  "trace_id": "7755321139078968799"
}

Server error (500)

{
  "error": "SERVER_SIDE_ERROR",
  "error_description": "Something went wrong.",
  "id": "ca21bb57-8255-46f0-b2f4-80613768ea6e",
  "trace_id": "7755321139078968799"
}

signing_url will only be valid for 30 minutes upon issuance. RPs are expected to create sign requests on demand upon signing.

We may change the format ofsigning_url at any point of time.

exchange_code should be treated as a secret as it will be used to get the signing result. Please do not share the code or put in your application logs.

Sample request

curl 'https://staging.sign.singpass.gov.sg/api/v3/sign-requests' \
  -H 'authorization: XXX' \
  -H 'content-type: application/octet-stream' \
  --data 'file=@path_to_your_test.pdf'

How to set signing coordinates

When starting a sign request, define the signature position using the x and y parameters in the JWT payload. These coordinates are percentage-based and relative to the PDF's dimensions, starting from the bottom left corner.

• y: Vertical position (0 to 1), where 0 is the bottom and 1 is the top.

• x: Horizontal position (0 to 1), where 0 is the left and 1 is the right.

We will not accept coordinates where a signature cannot be placed due to being outside the page boundaries. The signature size is fixed at 60x225 points, regardless of the PDF size.

Example
x = 0, y = 0 The bottom-left corner of the signature is positioned at the bottom-left corner of the document.
x = 0.5, y = 0.5 The bottom-left corner of the signature is positioned in the center of the document.
x = 1, y = 1 Error due to signature will be out of page area
x = 0.00001, y = 0.00001 Error due to max friction is 4

Privacy

The PDF document is held temporarily during the signing process and purged when no longer needed.