Sign with Singpass
Singpass Developer DocsAsk a Question
  • START HERE
    • Overview of Sign
    • How do our Digital Signatures work?
    • Frequently Asked Questions
  • FOR USERS
    • How to sign
    • Verifying Sign with Singpass Signatures
      • Loading Singpass Root Signing Certificate
  • FOR RELYING PARTIES
    • Use Cases
    • Getting Started
      • How to Onboard our API
      • Digital Signing Partners
        • Docusign
        • Tungsten Automation
        • OneSpan
        • Tessaract Technologies Pte Ltd
        • Netrust Pte Ltd
        • Modus Consulting
        • Redoc.co by Real Estate Doc Pte Ltd.
        • CrimsonLogic
        • Zoho Sign
        • Securemetric Technology Pte. Ltd.
        • Rently Pte. Ltd.
    • API Documentation
      • Document Signing V3
        • Initiate Sign Request
        • Redirect From Sign with Singpass
        • Accept Success Signing Webhook
        • Get Signing Result
        • JWKS Specification
        • Sign Portal
      • Document Signing V1
      • Transaction Signing
        • Embedding Singpass JS
        • Init Transaction Signing
        • Exchange Transaction Signature
    • UX Guidelines
      • User Journey Illustration
    • Support
Powered by GitBook
On this page
  • Path
  • Headers
  • Authorization token
  • Body
  • PDF Requirements
  • Response
  • How to set signing coordinates
  • Privacy

Was this helpful?

  1. FOR RELYING PARTIES
  2. API Documentation
  3. Document Signing V3

Initiate Sign Request

PreviousDocument Signing V3NextRedirect From Sign with Singpass

Last updated 3 hours ago

Was this helpful?

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 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 ()

  • 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

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

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

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"
}
{
  "error": "UNAUTHORIZED",
  "error_description": "Unauthorized.",
  "error_details": "JWT validation failed",
  "id": "ca21bb57-8255-46f0-b2f4-80613768ea6e",
  "trace_id": "7755321139078968799"
}
{
  "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.

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.

You can use the free tool to verify if your token is signed properly.

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

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

https://jwt.io/
Sign Portal
get the signing result
JSON Web Token
Singpass button