fino.sign API v1

Introduction

REST-API documentation of fino.sign API v1

Base URL: https://api.finosign.de

Welcome to the API documentation for the fino.sign API version 1. This documentation is designed to provide developers with essential information for the seamless integration of our digital signature service into their applications.

For a comprehensive implementation guide, please refer to our usage guide.

Resource Identifiers

Similar to other RESTful APIs, our API comprises resources that can be manipulated using the provided CRUD endpoints. Each resource accessible via the API is distinguished by a unique identifier. The type of identifier employed for our API resources is known as a Nano ID, which is characterized by a 12-character fixed length and is composed of alphanumeric characters within the range of A-Za-z0-9_-.

Rate Limiting

The API is rate limited to 100 requests per second per app. If this limit is exceeded any request to the API by the rate limited app will be declined with status 429 - Too Many Requests.

Changelog

1.4.0

Added ANNOTATION_EDIT_COMPLETE event
- This event will be triggered every time a user completes the annotation editing process (see v1.3.0)

1.3.0

Added a new feature, that allows placing annotations and form fields on signature documents through an interactive editor while the signature process is in preparation stage. This feature has to be activated by support per App.

Added JWT based signing security to enhance security on non-API endpoints (such as signing URLs or preparation URLs). This feature has to be activated by support per App and requires any of those URLs to be called with an additional JWT in the secure_token query parameter. For more information, see the usage guide.

Added external_reference for signers that have no email address.

GET /v1/signatures
- Response payload now includes data[].annotation_edit_url that contains the URL to the interactive PDF editor for placing annotations and form fields
POST /v1/signatures
- Response payload now includes data.annotation_edit_url that contains the URL to the interactive PDF editor for placing annotations and form fields
GET /v1/signatures/{signature}
- Response payload now includes data.annotation_edit_url that contains the URL to the interactive PDF editor for placing annotations and form fields
PATCH /v1/signatures/{signature}
- Response payload now includes data.annotation_edit_url that contains the URL to the interactive PDF editor for placing annotations and form fields
POST /v1/signatures/{signature}/open
- Response payload now includes data.annotation_edit_url that contains the URL to the interactive PDF editor for placing annotations and form fields
BREAKING CHANGES:
- Signers without an email address now require an external_reference to be provided. Previously, signers could be created with only a mobile number and no email address. Starting with this version, if no email address is provided, the external_reference parameter must be supplied. Requests that attempt to create or update signers with only a mobile number (without email and without external_reference) will fail with a validation error: "Either email or external_reference must be provided".
- POST /v1/signatures/{signature}/signers
  - New body parameter external_reference for providing an external reference ID for signers without an email address
  - Response payload now includes data.external_reference
- GET /v1/signatures/{signature}/signers/{signer}
  - Response payload now includes data.external_reference
- GET /v1/signatures/{signature}/signers
  - Response payload now includes data[].external_reference
- PATCH /v1/signatures/{signature}/signers/{signer}
  - New body parameter external_reference for providing an external reference ID for signers without an email address
  - Response payload now includes data.external_reference

1.2.0

POST /v1/signatures
- Request body parameter signers is now deprecated. Please use the dedicated signature signers create endpoint
- Response payload now includes data.signers[].notifications for reviewing notification settings
POST /v1/signatures/{signature}/signers
- New body parameter notifications for configuring notifications that a signer shall receive. Currently only E-Mail notifications are supported and need to be activated through support per app.
- Response payload now includes data.notifications for reviewing notification settings
GET /v1/signatures/{signature}/signers/{signer}
- Response payload now includes data.notifications for reviewing notification settings
GET /v1/signatures/{signature}/signers
- Response payload now includes data.signers[].notifications for reviewing notification settings
PATCH /v1/signatures/{signature}/signers/{signer}
- New body parameter notifications for configuring notifications that a signer shall receive. Currently only E-Mail notifications are supported and need to be activated through support per app.
- Response payload now includes data.notifications for reviewing notification settings

1.1.0

Added new processing status for signatures
- This is a new intermediate status between preparation and open. It indicates that the signature documents are being processed by fino.sign to prepare them for signing.
Webhook
- Webhooks have been reworked to allow publishing different events.
  - Note: To ensure backward compatibility, existing customers will not receive new event types until they have successfully integrated the changes on their end
  - Webhooks now include the X-Finosign-Event header that contains the event type
  - Webhooks may contain different request payloads based on the event type provided in the X-Finosign-Event header

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {API_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

To acquire an API token, please contact us directly, and our team will be happy to assist you in obtaining the necessary credentials.

Note: the API tokens used are considered confidential and must not be exposed to end users. If an API token is exposed by accident, it must be revoked immediately.

Signatures

A Signature resource serves as the foundational element within the API, representing the process by which entities affix their signatures to documents. This resource forms the cornerstone of the signature API, and all other resources within this API are related to it.

List all signatures

GET

https://api.finosign.de

/v1/signatures

requires authentication

List all signatures created by the authenticated app.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

string

Page number. Defaults to 1

Example:

sort

string

Sort the result according to the provided fields. Prepend '-' to sort in descending order. Defaults to created_at.

Allowed sorting fields are: created_at, updated_at

Example:

created_at,updated_at

Response Fields

data

object[]

An array containing the signatures of this page. Limited to 20 signatures per page.

string

The public id of this signature.

quality

string

The signature quality that will be used for this signature process.

Must be one of:

SES
AES
QES

status

string

The current status of this signature.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

withdraw_reason

string|null

The reason of withdrawal when status is withdrawn.

title

string|null

The optional title of this signature that gets shown to signers.

webhook_url

string|null

An optional webhook URL that will be used instead of the webhook URL of the app.

annotation_edit_url

string|null

A URL that may be used to edit PDF annotations while the signature is in PREPARATION stage (requires feature activation through support

expires_at

ISO-8601 formatted timestamp of when the signing link will expire.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

signers

object[]

An array of signers associated with this signature.

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

order

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

The firstname of the signer.

lastname

The lastname of the signer.

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

ident_method

The method of identification used by the signer.

status

The signature status for this signer.

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

The X.509 serial number of the certificate created after the signer has finished signing the documents represented in hexadecimal. This number should not be considered globally unique. For identification purposes use the certificate_fingerprint.

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

ISO-8601 formatted timestamp of when this resource has last been updated.

links

object

Pagination links

Create signature

POST

https://api.finosign.de

/v1/signatures

requires authentication

Create a new signature for starting a new signing process.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

quality

string

required

The quality of this signature. Must be a quality supported by the currently authenticated app.

Must be one of:

SES
AES
QES

Example:

SES

title

string

An optional title for this signature that will be shown to users. Must be between 2 and 100 characters.

Example:

My Signature Title

webhook_url

string

An optional webhook URL that will be used instead of the webhook URL of the app. Must be a valid URL.

Example:

https://myapp.test/webhook

expires_at

string

An optional expiry date (ISO-8601) for signing links. Must be a valid date. Must be a valid date in the format Y-m-d\TH:i:sP. Must be a date after today.

Example:

2024-01-01T12:00:00+0000

signers

object[]

[DEPRECATED: use dedicated create signer endpoint] ~~An array of signer-resources that represents entities that are prompted to fulfill the signing process.~~.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel. Must be between 1 and 255.

Example:

title

string

The title of the signer. Must not be greater than 200 characters.

Example:

Prof.

firstname

string

required

The firstname of the signer. Must be between 2 and 200 characters.

Example:

Katheryn

lastname

string

required

The lastname of the signer. Must be between 2 and 200 characters.

Example:

Langworth

string

The E-Mail address of the signer. Mutually exclusive with mobile_number when signature quality is SES. This field is required when signers.*.mobile_number is not present. Must be a valid email address. Must not be greater than 200 characters.

Example:

kayla.wiegand@yahoo.com

mobile_number

string

The mobile phone number of the signer. This number will be used for verification depending on the signature quality. Mutually exclusive with email when signature quality is SES. This field is required when signers.*.email is not present.

Example:

+4915228817386

redirect_url_success

string

required

A URL that the signer will be redirected to once the signature process has been finished successfully. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/success

redirect_url_error

string

required

A URL that the signer will be redirected to in case an error occurred while signing the documents. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/error

redirect_url_declined

string

required

A URL that the signer will be redirected to after they have declined their signature. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/declined

Response Fields

data

object

The created signature resource.

string

The public id of this signature.

quality

string

The signature quality that will be used for this signature process.

Must be one of:

SES
AES
QES

status

string

The current status of this signature.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

withdraw_reason

string|null

The reason of withdrawal when status is withdrawn.

title

string|null

The optional title of this signature that gets shown to signers.

webhook_url

string|null

An optional webhook URL that will be used instead of the webhook URL of the app.

annotation_edit_url

string|null

A URL that may be used to edit PDF annotations while the signature is in PREPARATION stage (requires feature activation through support

expires_at

ISO-8601 formatted timestamp of when the signing link will expire.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

signers

object[]

An array of signers associated with this signature.

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

order

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

The firstname of the signer.

lastname

The lastname of the signer.

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

ident_method

The method of identification used by the signer.

status

The signature status for this signer.

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

Body

{ "quality": "SES", "title": "My Signature Title", "webhook_url": "https:\/\/myapp.test\/webhook", "expires_at": "2024-01-01T12:00:00+0000", "signers": [ { "order": 1, "title": "Prof.", "firstname": "Katheryn", "lastname": "Langworth", "email": "kayla.wiegand@yahoo.com", "mobile_number": "+4915228817386", "redirect_url_success": "https:\/\/example.test\/success", "redirect_url_error": "https:\/\/example.test\/error", "redirect_url_declined": "https:\/\/example.test\/declined" } ] }

Received response

Example request:

curl --request POST \
    "https://api.finosign.de/v1/signatures" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"quality\": \"SES\",
    \"title\": \"My Signature Title\",
    \"webhook_url\": \"https:\\/\\/myapp.test\\/webhook\",
    \"expires_at\": \"2024-01-01T12:00:00+0000\",
    \"signers\": [
        {
            \"order\": 1,
            \"title\": \"Prof.\",
            \"firstname\": \"Katheryn\",
            \"lastname\": \"Langworth\",
            \"email\": \"kayla.wiegand@yahoo.com\",
            \"mobile_number\": \"+4915228817386\",
            \"redirect_url_success\": \"https:\\/\\/example.test\\/success\",
            \"redirect_url_error\": \"https:\\/\\/example.test\\/error\",
            \"redirect_url_declined\": \"https:\\/\\/example.test\\/declined\"
        }
    ]
}"

Example response:

{
    "data": {
        "id": "Cz7wWKv4ose9",
        "quality": "SES",
        "status": "preparation",
        "withdraw_reason": null,
        "title": null,
        "webhook_url": null,
        "annotation_edit_url": null,
        "expires_at": null,
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z",
        "signers": [
            {
                "id": "pTG41YEDE8bk",
                "external_reference": null,
                "signature_id": "Cz7wWKv4ose9",
                "order": 1,
                "title": null,
                "firstname": "Josiane",
                "lastname": "Schulist",
                "fullname": "Josiane Schulist",
                "email": "fay.kane@example.org",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "signed",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/Cz7wWKv4ose9/sign/WdkaOUEu7u",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "8bc284bf54ba",
                "certificate_fingerprint": "3dd4d91ce022952d90d16b02442f2816673bda067af654419bc607d872cf3146",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            },
            {
                "id": "KiAliy0qCZX4",
                "external_reference": null,
                "signature_id": "Cz7wWKv4ose9",
                "order": 1,
                "title": null,
                "firstname": "Jordi",
                "lastname": "Robel",
                "fullname": "Jordi Robel",
                "email": "loren.schmidt@example.net",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "open",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/Cz7wWKv4ose9/sign/5vJLOneYnc",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "c6db34c8cd3483dd45f83eb49d5e842b3b7f45f5",
                "certificate_fingerprint": "6fb64496d8acdbb9d0e4d41ae9b71fa70545f77355cf5c1ffa608e3d69e7427b",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            }
        ]
    }
}

Show signature

GET

https://api.finosign.de

/v1/signatures/{signature}

requires authentication

Retrieve an existing signature by the provided ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Response Fields

data

object

The signature resource found by the provided ID.

string

The public id of this signature.

quality

string

The signature quality that will be used for this signature process.

Must be one of:

SES
AES
QES

status

string

The current status of this signature.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

withdraw_reason

string|null

The reason of withdrawal when status is withdrawn.

title

string|null

The optional title of this signature that gets shown to signers.

webhook_url

string|null

An optional webhook URL that will be used instead of the webhook URL of the app.

annotation_edit_url

string|null

A URL that may be used to edit PDF annotations while the signature is in PREPARATION stage (requires feature activation through support

expires_at

ISO-8601 formatted timestamp of when the signing link will expire.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

signers

object[]

An array of signers associated with this signature.

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

order

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

The firstname of the signer.

lastname

The lastname of the signer.

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

ident_method

The method of identification used by the signer.

status

The signature status for this signer.

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": "7BcBmWTFqlBp",
        "quality": "SES",
        "status": "preparation",
        "withdraw_reason": null,
        "title": null,
        "webhook_url": null,
        "annotation_edit_url": null,
        "expires_at": null,
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z",
        "signers": [
            {
                "id": "DbC8ZDzeorsd",
                "external_reference": null,
                "signature_id": "7BcBmWTFqlBp",
                "order": 1,
                "title": null,
                "firstname": "Ana",
                "lastname": "Hagenes",
                "fullname": "Ana Hagenes",
                "email": "agottlieb@example.org",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "open",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/7BcBmWTFqlBp/sign/wf2tY3Nrb5",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "a7b8ad5047d355",
                "certificate_fingerprint": "537f995d3044ed6b56c17dfa33d5990ceae7cab3f0bfe20c0c2f277c5b75f34f",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            },
            {
                "id": "8j5FEi6LaWlE",
                "external_reference": null,
                "signature_id": "7BcBmWTFqlBp",
                "order": 1,
                "title": null,
                "firstname": "Justina",
                "lastname": "Gutmann",
                "fullname": "Justina Gutmann",
                "email": "brendon.brakus@example.net",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "open",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/7BcBmWTFqlBp/sign/ofPfQLBvjD",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "bd27f7687defc64d04",
                "certificate_fingerprint": "efbc831de127d83aae366b66699110da11b48568b4c8faa5fe39a3edf810e734",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            }
        ]
    }
}

Update signature

PATCH

https://api.finosign.de

/v1/signatures/{signature}

requires authentication

Update an existing signature with the provided values.

Note: Updating a signature is no longer possible once the signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Body Parameters

quality

string

required

The quality of this signature. Must be a quality supported by the currently authenticated app.

Must be one of:

SES
AES
QES

Example:

SES

title

string

An optional title for this signature that will be shown to users. Must be between 2 and 100 characters.

Example:

My Signature Title

webhook_url

string

An optional webhook URL that will be used instead of the webhook URL of the app. Must be a valid URL.

Example:

https://myapp.test/webhook

expires_at

string

An optional expiry date for signing links. Must be a valid date. Must be a valid date in the format Y-m-d\TH:i:sP. Must be a date after today.

Example:

2025-05-21 10:43:17

Response Fields

data

object

The updated signature resource.

string

The public id of this signature.

quality

string

The signature quality that will be used for this signature process.

Must be one of:

SES
AES
QES

status

string

The current status of this signature.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

withdraw_reason

string|null

The reason of withdrawal when status is withdrawn.

title

string|null

The optional title of this signature that gets shown to signers.

webhook_url

string|null

An optional webhook URL that will be used instead of the webhook URL of the app.

annotation_edit_url

string|null

A URL that may be used to edit PDF annotations while the signature is in PREPARATION stage (requires feature activation through support

expires_at

ISO-8601 formatted timestamp of when the signing link will expire.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

signers

object[]

An array of signers associated with this signature.

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

order

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

The firstname of the signer.

lastname

The lastname of the signer.

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

ident_method

The method of identification used by the signer.

status

The signature status for this signer.

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Body

{ "quality": "SES", "title": "My Signature Title", "webhook_url": "https:\/\/myapp.test\/webhook", "expires_at": "2025-05-21 10:43:17" }

Received response

Example request:

curl --request PATCH \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"quality\": \"SES\",
    \"title\": \"My Signature Title\",
    \"webhook_url\": \"https:\\/\\/myapp.test\\/webhook\",
    \"expires_at\": \"2025-05-21 10:43:17\"
}"

Example response:

{
    "data": {
        "id": "Cz7wWKv4ose9",
        "quality": "SES",
        "status": "preparation",
        "withdraw_reason": null,
        "title": null,
        "webhook_url": null,
        "annotation_edit_url": null,
        "expires_at": null,
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z",
        "signers": [
            {
                "id": "YEDE8bk6KiAl",
                "external_reference": null,
                "signature_id": "Cz7wWKv4ose9",
                "order": 1,
                "title": null,
                "firstname": "Josiane",
                "lastname": "Schulist",
                "fullname": "Josiane Schulist",
                "email": "eldridge.ankunding@example.com",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "signed",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/Cz7wWKv4ose9/sign/0NHrGldxM5",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "ea38ddc86bd99c6997e2e71e58b2fdb4e0e73e98",
                "certificate_fingerprint": "edb8cc9c754189631a731bd73ed78009569e243a394692b87d3a7e884194d417",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            },
            {
                "id": "y0qCZX4DbC8Z",
                "external_reference": null,
                "signature_id": "Cz7wWKv4ose9",
                "order": 1,
                "title": null,
                "firstname": "Kirk",
                "lastname": "Zulauf",
                "fullname": "Kirk Zulauf",
                "email": "haven33@example.com",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "signed",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/Cz7wWKv4ose9/sign/rkgVuw5FU1",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "bc62dc21ae1b2dbe4e62",
                "certificate_fingerprint": "1d9f7fc98bcd81c3c6a1ee002670f9b83078df681b688721b620fa6db0a3ec85",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            }
        ]
    }
}

Delete signature

DELETE

https://api.finosign.de

/v1/signatures/{signature}

requires authentication

Delete an existing signature and all its associated resources by the provided ID.

Note: Deleting a signature is no longer possible once the signature has reached signed stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Empty response]

Open Signature

POST

https://api.finosign.de

/v1/signatures/{signature}/open

requires authentication

Finalizes the preparation stage, making the documents ready to be signed.

Note: To finalize the preparation stage, at least one document and one signer is required.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Response Fields

data

object

The opened signature resource.

string

The public id of this signature.

quality

string

The signature quality that will be used for this signature process.

Must be one of:

SES
AES
QES

status

string

The current status of this signature.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

withdraw_reason

string|null

The reason of withdrawal when status is withdrawn.

title

string|null

The optional title of this signature that gets shown to signers.

webhook_url

string|null

An optional webhook URL that will be used instead of the webhook URL of the app.

annotation_edit_url

string|null

A URL that may be used to edit PDF annotations while the signature is in PREPARATION stage (requires feature activation through support

expires_at

ISO-8601 formatted timestamp of when the signing link will expire.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

signers

object[]

An array of signers associated with this signature.

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

order

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

The firstname of the signer.

lastname

The lastname of the signer.

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

ident_method

The method of identification used by the signer.

status

The signature status for this signer.

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request POST \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/open" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": "7BcBmWTFqlBp",
        "quality": "SES",
        "status": "preparation",
        "withdraw_reason": null,
        "title": null,
        "webhook_url": null,
        "annotation_edit_url": null,
        "expires_at": null,
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z",
        "signers": [
            {
                "id": "DzeorsdB8j5F",
                "external_reference": null,
                "signature_id": "7BcBmWTFqlBp",
                "order": 1,
                "title": null,
                "firstname": "Ana",
                "lastname": "Hagenes",
                "fullname": "Ana Hagenes",
                "email": "gutmann.justina@example.org",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "signed",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/7BcBmWTFqlBp/sign/9RBHrGIdEd",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "cf78a2e4c36769",
                "certificate_fingerprint": "56e8134f3cff9a4a16a78dae6ab29ff8b4ff73d184b1c0cb11463f1544c85be0",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            },
            {
                "id": "i6LaWlEO_4BP",
                "external_reference": null,
                "signature_id": "7BcBmWTFqlBp",
                "order": 1,
                "title": null,
                "firstname": "Keeley",
                "lastname": "Howell",
                "fullname": "Keeley Howell",
                "email": "tyrel47@example.net",
                "mobile_number": null,
                "notifications": {
                    "invite": false
                },
                "qes_ident_method": null,
                "qes_login_hint": null,
                "status": "signed",
                "decline_reason": null,
                "signing_url": "http://api.finosign.de/v1/signatures/7BcBmWTFqlBp/sign/6cfr3SL0gM",
                "redirect_url_success": null,
                "redirect_url_error": null,
                "redirect_url_declined": null,
                "certificate_serial_number": "90fd462df0",
                "certificate_fingerprint": "a54aad2fb1a35b9ba6e3944d537cf093de913bf36ce4ff6e8e773def4d847cb6",
                "created_at": "2025-12-05T14:37:01.000000Z",
                "updated_at": "2025-12-05T14:37:01.000000Z"
            }
        ]
    }
}

Signature Signers

A signer is an entity that is able to sign the documents in a signature process.

List all signers

GET

https://api.finosign.de

/v1/signatures/{signature}/signers

requires authentication

List all signing entities associated with the provided signature ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Response Fields

data

object[]

An array containing all signers associated with the provided signature ID.

string

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

signature_id

string

The public ID of the signature process that this signer belongs to.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

string

The firstname of the signer.

lastname

string

The lastname of the signer.

string

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

notifications

object

notification settings for this signer

ident_method

The method of identification used by the signer.

Must be one of:

intrum-video
fidentity
fidentity_nfc
fidentity_auto
ti8m
nect
sumsub-video
sumsub-auto
pxl-vision

status

string

The signature status for this signer.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/signers" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": "8bk6KiAliy0q",
            "external_reference": null,
            "signature_id": "qlBpTG41YEDE",
            "order": 1,
            "title": null,
            "firstname": "Katheryn",
            "lastname": "Langworth",
            "fullname": "Katheryn Langworth",
            "email": "abbigail.lehner@example.com",
            "mobile_number": null,
            "notifications": {
                "invite": false
            },
            "qes_ident_method": null,
            "qes_login_hint": null,
            "status": "signed",
            "decline_reason": null,
            "signing_url": "http://api.finosign.de/v1/signatures/qlBpTG41YEDE/sign/lD0I25EzSm",
            "redirect_url_success": null,
            "redirect_url_error": null,
            "redirect_url_declined": null,
            "certificate_serial_number": "b834bc2088edcb3ada6ba74d34",
            "certificate_fingerprint": "fd6a4485c6f912c11e36066fdad755da38a92aba6f0865792ac479d5e619c6d6",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        },
        {
            "id": "U4Uy3Vfi_EP6",
            "external_reference": null,
            "signature_id": "SoU2bGyyReuv",
            "order": 1,
            "title": null,
            "firstname": "Garry",
            "lastname": "Hackett",
            "fullname": "Garry Hackett",
            "email": "qdeckow@example.net",
            "mobile_number": null,
            "notifications": {
                "invite": false
            },
            "qes_ident_method": null,
            "qes_login_hint": null,
            "status": "open",
            "decline_reason": null,
            "signing_url": "http://api.finosign.de/v1/signatures/SoU2bGyyReuv/sign/hzXtWETmnk",
            "redirect_url_success": null,
            "redirect_url_error": null,
            "redirect_url_declined": null,
            "certificate_serial_number": "9f413c8f2a",
            "certificate_fingerprint": "1b2ee45b117ef75bb0ba7f2cb3f5fbbbb46d7920513ee99fdd9e1181d8dc74be",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        }
    ]
}

Create signer(s)

POST

https://api.finosign.de

/v1/signatures/{signature}/signers

requires authentication

Create one more multiple new signing entities for the signing process of the provided signature ID.

Note: Creating new signers is no longer possible once the signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Body Parameters

signers

object[]

An array of signer-resources that represents entities that are prompted to fulfill the signing process.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel. Must be between 1 and 255.

Example:

title

string

The title of the signer. Must not be greater than 200 characters.

Example:

Prof.

firstname

string

required

The firstname of the signer. Must be between 2 and 200 characters.

Example:

Katheryn

lastname

string

required

The lastname of the signer. Must be between 2 and 200 characters.

Example:

Langworth

string

The E-Mail address of the signer. Mutually exclusive with mobile_number when signature quality is SES. This field is required when signers.*.external_reference is not present. Must be a valid email address. Must not be greater than 200 characters.

Example:

kayla.wiegand@yahoo.com

external_reference

string

This field is required when signers.*.email is not present.

Example:

illum

qes_login_hint

string

The hint for the QES login method. Required when signature quality is QES. Must be one of "msisdn" (MobileID App) or "WBAUTHN" (Passkey).

Must be one of:

msisdn
WBAUTHN

Example:

msisdn

qes_ident_method

string

Must be one of:

intrum-video
intrum-auto
ti8m
fidentity
nect

Example:

ti8m

mobile_number

string

Example:

+4915228817386

notifications

object

An object to configure different notifications for this signer.

two_factor_identifier

string

The two factor identifier of the signer. This identifier will be placed onto the signature certificate. Usually a user id from your system. Requires activiation - contact support. This field is required when signers..two_factor_method or signers..two_factor_confirmed_at is present. Must be between 2 and 200 characters.

Example:

two_factor_method

string

The two factor method of the signer. Requires activation - contact support. This field is required when signers..two_factor_identifier or signers..two_factor_confirmed_at is present. Must be between 2 and 200 characters.

Example:

2FA Authenticator

two_factor_confirmed_at

string

The two factor confirmation at date of the signer. Must be in the past. Requires activation - contact support. This field is required when signers..two_factor_identifier or signers..two_factor_method is present. Must be a valid date in the format Y-m-d\TH:i:sP. Must be a date before or equal to now.

Example:

2024-01-01T12:00:00+0000

redirect_url_success

string

A URL that the signer will be redirected to once the signature process has been finished successfully. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/success

redirect_url_error

string

A URL that the signer will be redirected to in case an error occurred while signing the documents. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/error

redirect_url_declined

string

A URL that the signer will be redirected to after they have declined their signature. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/declined

Response Fields

data

object[]

The created signer resource.

string

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

signature_id

string

The public ID of the signature process that this signer belongs to.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

string

The firstname of the signer.

lastname

string

The lastname of the signer.

string

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

notifications

object

notification settings for this signer

ident_method

The method of identification used by the signer.

Must be one of:

intrum-video
fidentity
fidentity_nfc
fidentity_auto
ti8m
nect
sumsub-video
sumsub-auto
pxl-vision

status

string

The signature status for this signer.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Body

{ "signers": [ { "order": 1, "title": "Prof.", "firstname": "Katheryn", "lastname": "Langworth", "email": "kayla.wiegand@yahoo.com", "external_reference": "illum", "qes_login_hint": "msisdn", "qes_ident_method": "ti8m", "mobile_number": "+4915228817386", "notifications": { "invite": true }, "two_factor_identifier": "1", "two_factor_method": "2FA Authenticator", "two_factor_confirmed_at": "2024-01-01T12:00:00+0000", "redirect_url_success": "https:\/\/example.test\/success", "redirect_url_error": "https:\/\/example.test\/error", "redirect_url_declined": "https:\/\/example.test\/declined" } ] }

Received response

Example request:

curl --request POST \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/signers" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"signers\": [
        {
            \"order\": 1,
            \"title\": \"Prof.\",
            \"firstname\": \"Katheryn\",
            \"lastname\": \"Langworth\",
            \"email\": \"kayla.wiegand@yahoo.com\",
            \"external_reference\": \"illum\",
            \"qes_login_hint\": \"msisdn\",
            \"qes_ident_method\": \"ti8m\",
            \"mobile_number\": \"+4915228817386\",
            \"notifications\": {
                \"invite\": true
            },
            \"two_factor_identifier\": \"1\",
            \"two_factor_method\": \"2FA Authenticator\",
            \"two_factor_confirmed_at\": \"2024-01-01T12:00:00+0000\",
            \"redirect_url_success\": \"https:\\/\\/example.test\\/success\",
            \"redirect_url_error\": \"https:\\/\\/example.test\\/error\",
            \"redirect_url_declined\": \"https:\\/\\/example.test\\/declined\"
        }
    ]
}"

Example response:

{
    "data": [
        {
            "id": "iB7BcBmWTFql",
            "external_reference": null,
            "signature_id": "4ose9LJrby6-",
            "order": 1,
            "title": null,
            "firstname": "Myah",
            "lastname": "Dach",
            "fullname": "Myah Dach",
            "email": "dcasper@example.org",
            "mobile_number": null,
            "notifications": {
                "invite": false
            },
            "qes_ident_method": null,
            "qes_login_hint": null,
            "status": "signed",
            "decline_reason": null,
            "signing_url": "http://api.finosign.de/v1/signatures/4ose9LJrby6-/sign/f5mmoUMJ42",
            "redirect_url_success": null,
            "redirect_url_error": null,
            "redirect_url_declined": null,
            "certificate_serial_number": "56b59c62",
            "certificate_fingerprint": "501edacc24faa510783b2a94976e6e355598ef88d4cbe5f959ce009bf071f295",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        },
        {
            "id": "0qgY5lgs5GiS",
            "external_reference": null,
            "signature_id": "4YYSruY1AqJ-",
            "order": 1,
            "title": null,
            "firstname": "Elwin",
            "lastname": "Abshire",
            "fullname": "Elwin Abshire",
            "email": "fkihn@example.org",
            "mobile_number": null,
            "notifications": {
                "invite": false
            },
            "qes_ident_method": null,
            "qes_login_hint": null,
            "status": "open",
            "decline_reason": null,
            "signing_url": "http://api.finosign.de/v1/signatures/4YYSruY1AqJ-/sign/bYjGiqC7Zc",
            "redirect_url_success": null,
            "redirect_url_error": null,
            "redirect_url_declined": null,
            "certificate_serial_number": "567f25246a431628e92cdec6ec08e188",
            "certificate_fingerprint": "fdb0df9f2f4ebc0788d57a6a62d2be8540d8d44ef84cf434b9a20de5f92fabc8",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        }
    ]
}

Show signer

GET

https://api.finosign.de

/v1/signatures/{signature}/signers/{signer}

requires authentication

Retrieve a single signer associated with the provided signature ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

signer

string

required

The public ID of the signer resource.

Example:

hT1XfmsMNvsy

Response Fields

data

object

The signer resource found by the provided ID.

string

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

signature_id

string

The public ID of the signature process that this signer belongs to.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

string

The firstname of the signer.

lastname

string

The lastname of the signer.

string

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

notifications

object

notification settings for this signer

ident_method

The method of identification used by the signer.

Must be one of:

intrum-video
fidentity
fidentity_nfc
fidentity_auto
ti8m
nect
sumsub-video
sumsub-auto
pxl-vision

status

string

The signature status for this signer.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/signers/hT1XfmsMNvsy" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": "liy0qCZX4DbC",
        "external_reference": null,
        "signature_id": "1YEDE8bk6KiA",
        "order": 1,
        "title": null,
        "firstname": "Katheryn",
        "lastname": "Langworth",
        "fullname": "Katheryn Langworth",
        "email": "merlin.gibson@example.org",
        "mobile_number": null,
        "notifications": {
            "invite": false
        },
        "qes_ident_method": null,
        "qes_login_hint": null,
        "status": "signed",
        "decline_reason": null,
        "signing_url": "http://api.finosign.de/v1/signatures/1YEDE8bk6KiA/sign/1xaD0BRSvk",
        "redirect_url_success": null,
        "redirect_url_error": null,
        "redirect_url_declined": null,
        "certificate_serial_number": "26db46",
        "certificate_fingerprint": "eac2152f73f9a09739ba6682f4c824961c103f26698d0e6c9743c2192f5e627f",
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z"
    }
}

Update signer

PATCH

https://api.finosign.de

/v1/signatures/{signature}/signers/{signer}

requires authentication

Update information of an existing signer associated with the provided signature ID.

Note: Updating a signer is no longer possible once the associated signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

signer

string

required

The public ID of the signer resource.

Example:

hT1XfmsMNvsy

Body Parameters

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel. Must be between 1 and 255.

Example:

title

string

The title of the signer. Must not be greater than 200 characters.

Example:

Prof.

firstname

string

The firstname of the signer. Must be between 2 and 200 characters.

Example:

Katheryn

lastname

string

The lastname of the signer. Must be between 2 and 200 characters.

Example:

Langworth

string

The E-Mail address of the signer. Must be a valid email address. Must not be greater than 200 characters.

Example:

kayla.wiegand@yahoo.com

external_reference

string

Example:

illum

qes_login_hint

string

Must be one of:

msisdn
WBAUTHN

Example:

WBAUTHN

qes_ident_method

string

Must be one of:

intrum-video
intrum-auto
ti8m
fidentity
nect

Example:

ti8m

mobile_number

string

The mobile phone number of the signer. This number will be used for verification depending on the signature quality. This field is required when two_factor_identifier is not present.

Example:

+4915228817386

notifications

object[]

An object to configure different notifications for this signer.

two_factor_identifier

string

The two factor identifier of the signer. This identifier will be placed onto the signature certificate. Usually a user id from your system. Requires activiation - contact support. This field is required when two_factor_method or two_factor_confirmed_at is present. Must be between 2 and 200 characters.

Example:

two_factor_method

string

The two factor method of the signer. Requires activiation - contact support. This field is required when two_factor_identifier or two_factor_confirmed_at is present. Must be between 2 and 200 characters.

Example:

2FA Authenticator

two_factor_confirmed_at

string

The two factor confirmation at date of the signer. Must be in the past. Requires activiation - contact support. This field is required when two_factor_identifier or two_factor_method is present. Must be a valid date in the format Y-m-d\TH:i:sP. Must be a date before or equal to now.

Example:

2024-01-01T12:00:00+0000

redirect_url_success

string

A URL that the signer will be redirected to once the signature process has been finished successfully. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/success

redirect_url_error

string

A URL that the signer will be redirected to in case an error occurred while signing the documents. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/error

redirect_url_declined

string

A URL that the signer will be redirected to after they have declined their signature. Must use HTTPS protocol. Must be a valid URL.

Example:

https://example.test/declined

Response Fields

data

object

The updated signer resource.

string

The public ID of this signer.

external_reference

A unique ID that can be used in case a signer doesn't have an email address.

signature_id

string

The public ID of the signature process that this signer belongs to.

order

integer

The order index that this signer belongs to (starting at 1). Signers with the same order index are able to sign in parallel.

title

string|null

The title of the signer.

firstname

string

The firstname of the signer.

lastname

string

The lastname of the signer.

string

The E-Mail address of the signer.

mobile_number

string|null

The mobile phone number of the signer. This number will be used for verification depending on the signature quality.

notifications

object

notification settings for this signer

ident_method

The method of identification used by the signer.

Must be one of:

intrum-video
fidentity
fidentity_nfc
fidentity_auto
ti8m
nect
sumsub-video
sumsub-auto
pxl-vision

status

string

The signature status for this signer.

Must be one of:

preparation
processing
failed
declined
open
withdrawn
signed

decline_reason

string|null

An optional reason of why the signer has declined their signature. This value may still be null even if the status is declined indicating that the user did not provide a reason when declining.

redirect_url_success

A URL that the signer will be redirected to once the signature process has been finished successfully.

redirect_url_error

A URL that the signer will be redirected to in case an error occurred while signing the documents.

redirect_url_declined

A URL that the signer will be redirected to after they have declined their signature.

certificate_serial_number

string|null

certificate_fingerprint

string|null

A SHA-256 fingerprint across the whole certificate created after the signer has finished signing the documents. This fingerprint may be used to uniquely identify the signer.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Body

{ "order": 1, "title": "Prof.", "firstname": "Katheryn", "lastname": "Langworth", "email": "kayla.wiegand@yahoo.com", "external_reference": "illum", "qes_login_hint": "WBAUTHN", "qes_ident_method": "ti8m", "mobile_number": "+4915228817386", "notifications": [ { "invite": false } ], "two_factor_identifier": "1", "two_factor_method": "2FA Authenticator", "two_factor_confirmed_at": "2024-01-01T12:00:00+0000", "redirect_url_success": "https:\/\/example.test\/success", "redirect_url_error": "https:\/\/example.test\/error", "redirect_url_declined": "https:\/\/example.test\/declined" }

Received response

Example request:

curl --request PATCH \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/signers/hT1XfmsMNvsy" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"order\": 1,
    \"title\": \"Prof.\",
    \"firstname\": \"Katheryn\",
    \"lastname\": \"Langworth\",
    \"email\": \"kayla.wiegand@yahoo.com\",
    \"external_reference\": \"illum\",
    \"qes_login_hint\": \"WBAUTHN\",
    \"qes_ident_method\": \"ti8m\",
    \"mobile_number\": \"+4915228817386\",
    \"notifications\": [
        {
            \"invite\": false
        }
    ],
    \"two_factor_identifier\": \"1\",
    \"two_factor_method\": \"2FA Authenticator\",
    \"two_factor_confirmed_at\": \"2024-01-01T12:00:00+0000\",
    \"redirect_url_success\": \"https:\\/\\/example.test\\/success\",
    \"redirect_url_error\": \"https:\\/\\/example.test\\/error\",
    \"redirect_url_declined\": \"https:\\/\\/example.test\\/declined\"
}"

Example response:

{
    "data": {
        "id": "TFqlBpTG41YE",
        "external_reference": null,
        "signature_id": "by6-iB7BcBmW",
        "order": 1,
        "title": null,
        "firstname": "Myah",
        "lastname": "Dach",
        "fullname": "Myah Dach",
        "email": "winona.hermiston@example.com",
        "mobile_number": null,
        "notifications": {
            "invite": false
        },
        "qes_ident_method": null,
        "qes_login_hint": null,
        "status": "signed",
        "decline_reason": null,
        "signing_url": "http://api.finosign.de/v1/signatures/by6-iB7BcBmW/sign/pNUvQ8XOya",
        "redirect_url_success": null,
        "redirect_url_error": null,
        "redirect_url_declined": null,
        "certificate_serial_number": "a0a668d4f19a93088158f40f4c0b2e4103068b",
        "certificate_fingerprint": "1a592a77c303799c95deb1f329ed4a7eb075155ef6af2cdad9cb00aa18919865",
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z"
    }
}

Delete signer

DELETE

https://api.finosign.de

/v1/signatures/{signature}/signers/{signer}

requires authentication

Deletes a signer associated with the provided signature ID.

Note: Deleting a signer is no longer possible once the associated signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

signer

string

required

The public ID of the signer resource.

Example:

hT1XfmsMNvsy

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/signers/hT1XfmsMNvsy" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Empty response]

Signature Documents

A Signature Document represents any document that will be part of the signing process of the associated signature.

List all documents

GET

https://api.finosign.de

/v1/signatures/{signature}/documents

requires authentication

List all documents associated with the provided signature ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Response Fields

data

object[]

An array containing all documents associated with the provided signature ID.

string

The public id of this document.

filename

string

The name of the file of this document (without extension).

extension

string

The file extension of this document.

name

string

filename and extension combined forming the full filename.

mime_type

string

The MIME-Type of this document.

bytes

integer

The size of the document in bytes.

file_hash

string

A SHA-256 hash of the file.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/documents" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": "G8vDq3P3WA09",
            "filename": "o1EgFvsUyn",
            "extension": "pdf",
            "name": "o1EgFvsUyn.pdf",
            "mime_type": "application/pdf",
            "bytes": 465983,
            "file_hash": "92cb5f5f76af2e3f6218b8c18337d99f12eedae63030cbd816310e717793538d",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        },
        {
            "id": "GtRIiX8l-l97",
            "filename": "35ILjc0aYV",
            "extension": "pdf",
            "name": "35ILjc0aYV.pdf",
            "mime_type": "application/pdf",
            "bytes": 804521,
            "file_hash": "852f07f5c1bf311a9ebe3819a1f27464fe0408200752e7bc7526456bf41fd858",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        }
    ]
}

Upload document(s)

POST

https://api.finosign.de

/v1/signatures/{signature}/documents

requires authentication

Upload one or multiple new documents that will become part of the signing process of the provided signature ID.

Note: Uploading new documents is no longer possible once the associated signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

multipart/form-data

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Body Parameters

files

file[]

The file representing the document that shall be uploaded. The filename must contain an extension. Must be a file. Must not be greater than 51200 kilobytes.

Example:

Response Fields

data

object[]

The created document resource.

string

The public id of this document.

filename

string

The name of the file of this document (without extension).

extension

string

The file extension of this document.

name

string

filename and extension combined forming the full filename.

mime_type

string

The MIME-Type of this document.

bytes

integer

The size of the document in bytes.

file_hash

string

A SHA-256 hash of the file.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Body

Received response

Example request:

curl --request POST \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/documents" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "files[]=@/tmp/php4bhQyk"

Example response:

{
    "data": [
        {
            "id": "Jrby6-iB7BcB",
            "filename": "e6xmu1XlxX",
            "extension": "pdf",
            "name": "e6xmu1XlxX.pdf",
            "mime_type": "application/pdf",
            "bytes": 932763,
            "file_hash": "403b7fd050567c62202ca7ecf65c0a5203f5be81e46d044cd637752454c158bb",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        },
        {
            "id": "YYSruY1AqJ-0",
            "filename": "jkQJJ4ZNgS",
            "extension": "pdf",
            "name": "jkQJJ4ZNgS.pdf",
            "mime_type": "application/pdf",
            "bytes": 68120,
            "file_hash": "965c91122e73c5c8bff0e6aa79cc6a743791a826ba3266df968d6b79ee2f8d1e",
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        }
    ]
}

Show document

GET

https://api.finosign.de

/v1/signatures/{signature}/documents/{document}

requires authentication

Retrieve information about a document associated with the provided signature ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

document

string

required

The public ID of the document resource.

Example:

hT1XfmsMNvsy

Response Fields

data

object

The document resource found by the provided ID.

string

The public id of this document.

filename

string

The name of the file of this document (without extension).

extension

string

The file extension of this document.

name

string

filename and extension combined forming the full filename.

mime_type

string

The MIME-Type of this document.

bytes

integer

The size of the document in bytes.

file_hash

string

A SHA-256 hash of the file.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/documents/hT1XfmsMNvsy" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": "TG41YEDE8bk6",
        "filename": "dX5KdIDTwt",
        "extension": "pdf",
        "name": "dX5KdIDTwt.pdf",
        "mime_type": "application/pdf",
        "bytes": 374363,
        "file_hash": "fb171663c6e12f9a0fbf8477adbf148938beee58c28ea7f311b4c0a5ed45f378",
        "created_at": "2025-12-05T14:37:01.000000Z",
        "updated_at": "2025-12-05T14:37:01.000000Z"
    }
}

Delete document

DELETE

https://api.finosign.de

/v1/signatures/{signature}/documents/{document}

requires authentication

Delete a document associated with the provided signature ID.

Note: Deleting a document is no longer possible once the associated signature has left preparation stage.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

document

string

required

The public ID of the document resource.

Example:

hT1XfmsMNvsy

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/documents/hT1XfmsMNvsy" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Empty response]

Download Document

GET

https://api.finosign.de

/v1/signatures/{signature}/documents/{document}/download

requires authentication

Retrieve a signed document of a completed signature process.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

document

string

required

The public ID of the document resource.

Example:

hT1XfmsMNvsy

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/documents/hT1XfmsMNvsy/download" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Binary data] -  The requested document

Signature Logs

Actions performed in a signature process are logged per signature. A signature log represents a single action taken by an entity regarding a signature.

List logs of Signature

GET

https://api.finosign.de

/v1/signatures/{signature}/logs

requires authentication

List all logs associated with the provided signature ID.

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

Response Fields

data

object[]

An array containing all logs associated with the provided signature ID.

string

The public id of this log entry.

ip_address

string|null

The IPv4 or IPv6 address of the entity performing the action. May be null indicating that the action has been performed by internal systems.

user_agent

string|null

The user-agent of the entity performing the action May be null indicating that the action has been performed by internal systems.

user_agent_hash

string|null

A SHA-256 hash of the user_agent field that can be used for fingerprinting.

message

string|null

A message describing the log entry.

data

object|null

An optional payload for the specific log entry containing metadata.

created_at

string

ISO-8601 formatted timestamp of when this resource has been created.

updated_at

string

ISO-8601 formatted timestamp of when this resource has last been updated.

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/logs" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": "dB8j5FEi6LaW",
            "ip_address": "5e58:8b51:e6a5:4219:6b4d:9848:1b09:9794",
            "user_agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/536.1 (KHTML, like Gecko) Chrome/97.0.4631.50 Safari/536.1 EdgA/97.01095.73",
            "user_agent_hash": "5f47c1162a758cc1f6b6412f8dec7f96f1df0d2bf3c64a33cc14face823da083",
            "message": "signature_declined",
            "data": {},
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        },
        {
            "id": "yfHJgXpdKynz",
            "ip_address": "4.121.110.94",
            "user_agent": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0; Trident/5.0)",
            "user_agent_hash": "90163883f95ca8f099366c790343cdb2f7fad7fde5f66408181bb8372cb7ffde",
            "message": "signature_signed",
            "data": {},
            "created_at": "2025-12-05T14:37:01.000000Z",
            "updated_at": "2025-12-05T14:37:01.000000Z"
        }
    ]
}

Endpoints

GET v1/signatures/{signature}/sign/{token}/message

GET

https://api.finosign.de

/v1/signatures/{signature}/sign/{token}/message

requires authentication

Headers

Authorization

Example:

Bearer {API_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

signature

string

required

The public ID of the signature resource.

Example:

zHQAQwQpBDmq

token

string

required

Example:

illum

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.finosign.de/v1/signatures/zHQAQwQpBDmq/sign/illum/message" \
    --header "Authorization: Bearer {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response: