API-only guide

This guide provides step-by-step instructions on how to integrate Qualified Electronic Signature via our API.

Before you begin, make sure you have completed the signature setup.

Flow

Click to magnify

1. Authenticate

Create an access token to authenticate in our API:

You provide your Fourthline API key.
You receive an access_token.

📖

Create access token

Open Recipe

API Reference – Create access token

Important

For security, access tokens are valid for 1 hour only.
If your token expires, make another Create access token request.

2. Create workflow

Create a Qualified Electronic Signataure workflow:

You specify the workflowName and provide your unique identifier for the client.
You receive a workflowId and a Fourthline clientId.

📖

Create Qualified Electronic Signature workflow

Open Recipe

API Reference – Create workflow

Status: The signature status changes to new and we send the relevant webhook notification.

Fourthline checks that the status of the related Identity Verification case is one of the following:

Flow	Status
Completed verification	`completed` with a risk score of `200` – `400` (not `500`)
Pending verification	`new`, `pending`, or `completed` with a risk score of `200` – `400` (not `500`)

If the Identity Verification case status is valid, we perform the initial ID document check, and (if configured) the sanctions check.

Status: The signature status changes to one of the following and we send a webhook notification:

Status	Description	Action
`pending`	The client is eligible for a signature.	Wait.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.

3. Upload documents to sign

Upload to Fourthline the document(s) you want the client to sign:

You provide the workflowId, information about the documents, and the files.
A successful response is empty.

📖

Upload documents to sign

Open Recipe

API Reference – Upload documents to sign

Status: The signature status remains pending.

4. Upload mobile number

Upload the client's mobile phone number for them to receive the passcode SMS to confirm the signature:

You provide the workflowId and the phone number.
A successful response is empty.

📖

Upload mobile phone number

Open Recipe

API Reference – Upload mobile phone number

Status: The signature status changes to one of the following and we send a webhook notification:

Status	Description	Action
`user_consent_required`	The client is eligible for a signature.	Get the signature details, and then approve the documents to sign within 2 hours or the signature flow expires, you receive a 422 error, and you must create a new workflow for a signature only. After 24 hours or the status changes to `error`.
`selfie_required`	The Identity Verification case was completed more than 24 hours ago, or less than 24 hours ago and the client's device model is different, and we need to confirm the client's identity.	Upload a selfie within 24 hours or the status changes to `error`.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.
`error`	An error occurred. If the system can recover after the error, the status changes to a previous status.	If the system can't recover, create a new workflow for a signature only.

5. Get signature details

When the signature status is user_consent_required, to prepare for the document approval step, get the signature details:

You provide the signatureId (same value as the workflowId) and optionally specify the language of the QTSP legal conditions.
You receive the clientId, verificationId, mobile phone number, documents to sign, legal conditions, and passcode details.

📖

Get signature details

Open Recipe

API Reference – Get signature details

Important

• You must be able to prove which client viewed which versions of the legal conditions and when.
• To reduce the number of steps, consider displaying the documents to sign and the legal conditions on the same page in your UI.

6. Approve documents to sign

When the signature status is user_consent_required, inform Fourthline that the client has approved the documents to sign and accepted the legal conditions:

You provide the signatureId (same value as the workflowId), the approved documents and legal conditions accepted, and optionally specify the language of the passcode.
You receive an attemptId for this approval attempt.

📖

Approve documents to sign

Open Recipe

API Reference – Approve documents to sign

Important

Inform Fourthline within 2 hours or the approval expires and you must restart the signature flow.

Status: The signature status changes to one of the following:

Status	Description	Action
`confirmation_required`	The document(s) to sign were successfully approved. If you don't confirm the signature within: • 1 hour: The signature flow expires, you receive a `422` error, and you must create a new workflow for a signature only. • 24 hours: The status changes to error.	Confirm the signature.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.
`error`	An error occurred. If the system can recover after the error, the status changes to a previous status.	If the system can't recover, create a new workflow for a signature only.

7. Confirm signature

When the signature status is confirmation_required, the QTSP creates the certificate with the client's first and last names and ID document number:

Flow	Description
Completed verification	The certificate uses the details confirmed when processing the Identity Verification case.
Pending verification	The certificate uses the details extracted (in order of reliability) from the ID document NFC chip or MRZ or VIZ during Identity Verification case processing, or failing those, the client's input. These details haven't yet been confirmed in case processing.

The QTSP then sends you and the client an SMS containing the one-time passcode. This also confirms that the client has access to the mobile phone number you have previously verified.

Within 2 hours of receiving the passcode, the client enters it in the signature flow to confirm signing the documents.

Tip

If the client doesn't receive the passcode or something goes wrong when they try to enter it in the signature flow, you can resend it to them a maximum of 4 times via a Resend signature passcode request.

Validate the passcode and close the signature flow:

You provide the signatureId (same value as the workflowId) and the passcode.
You receive an attemptId for this confirmation attempt.

📖

Confirm signature

Open Recipe

API Reference – Confirm signature

Fourthline places the signature on the documents.

Flow	Description
Completed verification	The signature is valid immediately.
Pending verification	When the Identity Verification case is completed, the extracted details on the certificate are compared to the confirmed details from the case. If the details: • Match: Fourthline makes the document legally binding by countersigning and adding a timestamp. • Don't match: Restart the signature workflow for the client (not the Identity Verification flow). On the reattempt, the certificate uses the confirmed details and Fourthline countersigns at the end of the flow.

Flow

Description

Completed verification

The signature is valid immediately.

Pending verification

When the Identity Verification case is completed, the extracted details on the certificate are compared to the confirmed details from the case.
If the details:
• Match: Fourthline makes the document legally binding by countersigning and adding a timestamp.
• Don't match: Restart the signature workflow for the client (not the Identity Verification flow).
On the reattempt, the certificate uses the confirmed details and Fourthline countersigns at the end of the flow.

Note

The ID document number, and the client's first name and second name must match.
Third names may be cut off in the MRZ.

Status: The signature status changes to one of the following:

Status	Description	Action
`signed`	The signed documents are available.	Download the signed documents.
`pending_verification` Pending flow only	The client has completed the signature flow, but we are still processing the Identity Verification case.	Wait for the next status notification.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.
`invalid_signature` Pending flow only	The extracted certificate details don't match the confirmed details from the Identity Verification case.	Restart the signature flow.
`error`	An error occurred. If the system can recover after the error, the status changes to a previous status.	If the system can't recover, create a new workflow for a signature flow only.

Check signature status

When you receive webhook notifications, we recommend also checking the signature status:

You provide the signatureId (same value as the workflowId).
You receive the current status and status code.

📖

Get signature status

Open Recipe

API Reference – Get signature status

8. Download signed documents

When the signature status is signed, download each signed document:

You provide the signatureId (same value as the workflowId) and relevant documentId.
You receive a message in plain text and the PDF document.

📖

Download signed documents

Open Recipe

API Reference – Get signed document

If you have the fallback QTSP option configured, check if an InfoCert contract was generated, which you are required to download and share with the client:

You provide the signatureId (same value as the workflowId).
You receive one of the following empty responses:
- 200: The signature flow was directed to InfoCert and the response returns the contract to share with the client.
- 204: The signature flow was directed to Namirial so no contract is returned.

📖

Get InfoCert contract

Open Recipe

API Reference – Get InfoCert contract

Success

You have integrated Qualified Electronic Signature!

Top of page