Certifaction Signing API
Sign files and request signatures
OpenAPI Specification
openapi: 3.1.0
info:
title: '{{ .ProductName }} Admin Account Signing API'
description: '{{ .ProductName }} Admin API is used to manage users, roles and teamspaces.
## Setup requirements
Authentication is required to perform some operations. Please refer to the [Authentication](https://developers.certifaction.com/en/references/authentication) section to obtain an API Key or token.
'
version: ''
servers:
- url: '{{ .APIServerURL }}'
security:
- api_key: []
tags:
- name: Signing
description: Sign files and request signatures
paths:
/prepare:
post:
operationId: prepare_file
parameters:
- $ref: '#/components/parameters/digital_twin'
- $ref: '#/components/parameters/pdf-a'
- $ref: '#/components/parameters/accept_language'
- $ref: '#/components/parameters/prepare_scope'
- $ref: '#/components/parameters/signature_anchors'
- $ref: '#/components/parameters/additional_page'
- $ref: '#/components/parameters/qr_llx'
- $ref: '#/components/parameters/qr_lly'
- $ref: '#/components/parameters/qr_height'
- $ref: '#/components/parameters/qr_page'
- $ref: '#/components/parameters/encryption_key'
- $ref: '#/components/parameters/password_encryption'
summary: Prepare a file for signing
requestBody:
description: The file to prepare.
required: true
content:
application/pdf: {}
responses:
200:
description: The prepared file content.
content:
application/pdf:
schema:
type: string
400:
$ref: '#/components/responses/bad_request'
401:
$ref: '#/components/responses/unauthorized'
tags:
- Signing
/sign:
post:
operationId: sign_file
parameters:
- $ref: '#/components/parameters/digital_twin'
- $ref: '#/components/parameters/pdf-a'
- $ref: '#/components/parameters/accept_language'
- $ref: '#/components/parameters/additional_page'
- $ref: '#/components/parameters/qr_llx'
- $ref: '#/components/parameters/qr_lly'
- $ref: '#/components/parameters/qr_height'
- $ref: '#/components/parameters/qr_page'
- $ref: '#/components/parameters/encryption_key'
- $ref: '#/components/parameters/password_encryption'
- name: hash
in: query
schema:
type: string
- name: note
in: query
schema:
type: string
maxLength: 255
- name: legal-weight
in: query
schema:
type: string
enum:
- AES
- QES
- SES
- name: jurisdiction
in: query
schema:
type: string
enum:
- eIDAS
- ZertES
- name: filename
in: query
schema:
type: string
- name: no-prepare
in: query
schema:
type: boolean
- name: position-x
description: 'The x-coordinate of the signature from the bottom-left of the page.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
- name: position-y
description: 'The y-coordinate of the signature from the bottom-left of the page.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
- name: height
description: The height of the signature card. This is required when `additional-page=false`.
in: query
schema:
type: number
- name: page
description: The page to place the signature on. This is required when `additional-page=false`.
in: query
schema:
type: integer
minimum: 1
summary: Sign a file
requestBody:
description: The file to sign.
required: true
content:
application/pdf: {}
responses:
200:
description: The signed file content.
content:
application/pdf:
schema:
type: string
400:
$ref: '#/components/responses/bad_request'
401:
$ref: '#/components/responses/unauthorized'
tags:
- Signing
/request/create:
post:
operationId: request_signature
parameters:
- $ref: '#/components/parameters/digital_twin'
- $ref: '#/components/parameters/pdf-a'
- name: send-email
in: query
schema:
type: boolean
default: false
description: 'If `send-email=true`, the server will send the signature request to the signer''s email
and also send reminder emails to get them to sign.
'
- name: name
in: query
schema:
type: string
description: 'The full name of the signer. You can omit this and send the name in parts using
`first-name`, `middle-names`, and `last-name`.
'
- name: first-name
in: query
schema:
type: string
- name: middle-names
in: query
schema:
type: string
- name: last-name
in: query
schema:
type: string
- name: email
in: query
schema:
type: string
format: email
description: The signer's email address.
required: true
- name: mobile-phone
in: query
schema:
type: string
- name: citizenship
in: query
schema:
type: string
- name: birthday
in: query
schema:
type: string
- name: gender
in: query
schema:
type: string
- name: domicile
in: query
schema:
type: string
- name: webhook-url
in: query
schema:
type: string
format: url
description: 'URL-encoded callback URL that will be called with a `POST` request upon completion of the signature.
See [Webhooks](https://developers.certifaction.com/en/guides/webhooks) for authentication and
retry details.
'
- $ref: '#/components/parameters/accept_language'
- $ref: '#/components/parameters/additional_page'
- $ref: '#/components/parameters/qr_llx'
- $ref: '#/components/parameters/qr_lly'
- $ref: '#/components/parameters/qr_height'
- $ref: '#/components/parameters/qr_page'
- $ref: '#/components/parameters/encryption_key'
- $ref: '#/components/parameters/password_encryption'
- name: with-password
in: query
schema:
type: boolean
description: 'Protect the request using a password so that only the password bearer can sign.
If enabled, a password will be generated. Send the password, together with the request URL, to the signer.
'
- name: hash
in: query
schema:
type: string
- name: message
in: query
schema:
type: string
maxLength: 255
- name: transaction-id
in: query
schema:
type: string
- name: auto-sign
in: query
schema:
type: boolean
default: false
- name: legal-weight
in: query
schema:
$ref: '#/components/schemas/legal_weight'
- name: jurisdiction
in: query
schema:
type: string
enum:
- eIDAS
- ZertES
- name: filename
in: query
schema:
type: string
- name: no-prepare
in: query
schema:
type: boolean
- name: position-x
description: 'The x-coordinate of the signature from the bottom-left of the page.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
- name: position-y
description: 'The y-coordinate of the signature from the bottom-left of the page.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
- name: height
description: The height of the signature card. This is required when `additional-page=false`.
in: query
schema:
type: number
- name: page
description: The page to place the signature on. This is required when `additional-page=false`.
in: query
schema:
type: integer
minimum: 1
summary: Request a signature
requestBody:
description: The files to sign
required: true
content:
application/pdf: {}
application/json:
schema:
properties:
files:
type: array
items:
type: object
properties:
url:
type: string
format: url
description: 'DA URL of the documents to sign.
'
name:
type: string
description: 'Name of the document. This is used in the signature request email.
'
application/x-www-form-urlencoded:
schema:
properties:
files:
type: array
items:
type: string
format: url
description: 'DA URLs to the documents to sign. Previous signing links can be reused.
If a link to a password-protected request is provided, also pass the `password` parameter.
'
multipart/form-data:
schema:
properties:
files:
type: array
items:
type: string
format: binary
description: Upload PDF documents to sign.
encoding:
files:
contentType: application/pdf
style: form
responses:
200:
description: The signature request was created.
content:
application/json:
schema:
properties:
request_url:
type: string
format: url
password:
type: string
400:
$ref: '#/components/responses/bad_request'
401:
$ref: '#/components/responses/unauthorized'
409:
description: The signer already has a pending signature request for the file.
tags:
- Signing
/request/cancel:
post:
operationId: cancel_request
summary: Cancel signature request for signer
parameters:
- name: email
in: query
schema:
type: string
format: email
description: The email of the signer to cancel the request for.
required: true
- name: note
in: query
schema:
type: string
description: A message to the signer. You can use this to explain why you cancelled the request.
requestBody:
description: A file used in the signature request.
required: true
content:
application/pdf: {}
responses:
204:
description: The signature request to the given signer was cancelled.
400:
description: 'Check that:
1. The `email` parameter was provided.
2. The file provided has been prepared and can be read.
'
401:
$ref: '#/components/responses/unauthorized'
403:
description: You cannot cancel the request at this time. It could be because the signer has signed already.
404:
description: Either the file provided or the signer email was not found.
tags:
- Signing
/request/cancel/all:
post:
operationId: cancel_request_all
summary: Cancel signature requests for file
parameters:
- name: note
in: query
schema:
type: string
description: A message to the signers. You can use this to explain why you cancelled the request.
requestBody:
description: A file used in the signature request.
required: true
content:
application/pdf: {}
responses:
204:
description: All pending signature requests for the file were cancelled.
400:
description: Check that the file provided has been prepared and can be read.
401:
$ref: '#/components/responses/unauthorized'
403:
description: You cannot cancel the requests at this time. It could be because a signer has signed already.
404:
description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
tags:
- Signing
/request/list:
post:
deprecated: true
operationId: list_requests
summary: List signature requests for file
requestBody:
description: A file (or a file URL) used in the signature request.
required: true
content:
application/x-www-form-urlencoded:
schema:
properties:
file:
type: string
format: url
password:
type: string
required:
- file
multipart/form-data:
schema:
properties:
file:
type: string
format: binary
required:
- file
encoding:
file:
contentType: application/pdf
responses:
200:
description: List of signature requests for the file.
content:
application/json:
schema:
properties:
id:
type: string
legal_weight:
$ref: '#/components/schemas/legal_weight'
cancelled:
type: boolean
signed:
type: boolean
signer:
$ref: '#/components/schemas/user'
requester:
$ref: '#/components/schemas/user'
400:
description: Check that the file provided has been prepared and can be read.
401:
$ref: '#/components/responses/unauthorized'
403:
description: You cannot list signature requests for this file.
404:
description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
tags:
- Signing
/request/status:
get:
operationId: request_status
summary: Show status of signature request
parameters:
- name: request_url
in: query
required: true
schema:
type: string
format: url
description: The URL of the signature request to check.
- name: password
in: query
schema:
type: string
description: Password for password encrypted requests
responses:
200:
description: Status of the signature request.
content:
application/json:
schema:
properties:
url:
type: string
format: url
id:
type: string
createdAt:
type: string
format: date-time
cancelled:
type: boolean
envelope_items:
type: object
properties:
legal_weight:
$ref: '#/components/schemas/legal_weight'
jurisdiction:
type: string
status:
$ref: '#/components/schemas/envelope_item_status'
signed_at:
type: string
format: date-time
file_url:
type: string
format: url
file_id:
type: string
signer:
type: object
properties:
email:
type: string
format: email
used_identification_at:
type: string
format: date-time
identification_method:
type: string
400:
description: Check that the file provided has been prepared and can be read.
401:
$ref: '#/components/responses/unauthorized'
403:
description: You cannot list signature requests for this file.
404:
description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
tags:
- Signing
/request/file/status:
get:
operationId: file_requests_status
summary: Show status of signature requests of given file
parameters:
- name: file_url
in: query
required: true
schema:
type: string
format: url
description: The DA URL of the file to check.
- name: password
in: query
schema:
type: string
description: Password for password encrypted document.
responses:
200:
description: File status across all signature requests.
content:
application/json:
schema:
properties:
file_url:
type: string
format: url
file_id:
type: string
signature_requests:
type: array
items:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
cancelled:
type: boolean
envelope_items:
type: object
properties:
legal_weight:
$ref: '#/components/schemas/legal_weight'
jurisdiction:
type: string
status:
$ref: '#/components/schemas/envelope_item_status'
signed_at:
type: string
format: date-time
file_url:
type: string
format: url
file_id:
type: string
signer:
type: object
properties:
email:
type: string
format: email
used_identification_at:
type: string
format: date-time
identification_method:
type: string
400:
description: Check that the file provided has been prepared and can be read.
401:
$ref: '#/components/responses/unauthorized'
403:
description: You cannot list signature requests for this file.
404:
description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
tags:
- Signing
/qes/check:
post:
summary: Check account QES status
requestBody:
content:
application/json:
schema:
properties:
jurisdiction:
type: string
required:
- jurisdiction
responses:
200:
description: QES is enabled for your account.
400:
$ref: '#/components/responses/bad_request'
401:
$ref: '#/components/responses/unauthorized'
404:
description: QES is disabled for your account.
tags:
- Signing
components:
schemas:
identity:
properties:
uid:
type: string
user_uid:
type: string
issuer:
type: string
status:
type: string
verification_url:
type: string
verification_id:
type: string
evidence_url:
type: string
proof:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
birthday:
type: string
signature_level:
type: string
signature_jurisdiction:
type: string
required:
- uid
- user_uid
- issuer
- status
- verification_url
- verification_id
- evidence_url
- proof
- name
- given_name
- family_name
- birthday
language:
type: string
enum:
- de
- en
- fr
- it
organization:
properties:
id:
type: string
name:
type: string
maxLength: 80
minLength: 2
subscription_type:
type: string
quota:
type: integer
required:
- id
legal_weight:
type: string
enum:
- AES
- QES
- SES
envelope_item_status:
type: string
enum:
- unsigned
- awaiting_upload
- signed
- cancelled
prepare_scope:
type: string
enum:
- sign
- attachment
user:
properties:
id:
type: integer
uid:
type: string
external_id:
type: string
email:
type: string
title:
type: string
name:
type: string
first_name:
type: string
middle_names:
type: string
last_name:
type: string
affiliation:
type: string
address:
type: string
postalcode:
type: string
location:
type: string
eth_address:
type: string
quota:
type: integer
disabled:
type: boolean
file_suffix:
type: string
permissions:
type: array
items:
type: string
subscription_type:
type: string
encrypt_claims:
type: boolean
verified_by:
type: string
features:
type: object
organizations:
type: array
items:
$ref: '#/components/schemas/organization'
identities:
type: array
items:
$ref: '#/components/schemas/identity'
theme:
properties:
name:
type: string
required:
- name
name_verified:
type: boolean
parameters:
signature_anchors:
name: signature-anchors
description: 'Place a signature card relative to plain text already present in the document. The value is a
URL-encoded JSON object describing a single anchor; repeat the parameter to add more anchors
(one object each). When provided, placeholder mode is enabled automatically: prepare the
document with the anchors first, then sign each resulting placeholder via `/sign` or
`/register` using its `id`.
**Important**: on `/prepare`, anchors are only supported with `scope=sign` and a PAdES-enabled
account. The anchor text must be extractable from the PDF (searchable text, not a scanned
image).
Fields (`id` and `anchor` are required; entries missing either are rejected with `400`):
- `id`: unique placeholder name to sign against.
- `anchor`: plain text to search for in the document.
- `occurrence`: which match to use when the anchor repeats (1-based, defaults to 1).
- `x`, `y`: offset from the matched text''s top-left (`x`+ right, `y`+ down); units `cm`/`mm`/`in`/`pt`.
- `w`, `h`: card size (units `cm`/`mm`/`in`/`pt`). Only `w` derives the height from the aspect ratio; only `h` derives the width; without either, the base width is used.
- `removeAnchor`: strip the matched anchor text from the PDF (defaults to `false`).
JSON values must be percent-encoded in the query string, e.g. `{"id":"signer1","anchor":"signatures"}`
becomes `%7B%22id%22%3A%22signer1%22%2C%22anchor%22%3A%22signatures%22%7D`.
'
in: query
explode: true
schema:
type: array
items:
type: string
encryption_key:
name: encryption-key
description: A hexadecimal string to encrypt the document with.
in: query
schema:
type: string
accept_language:
name: Accept-Language
description: 'The language for text object placed added to the document. Pass `de` for German, `en` for English,
`fr` for French, or `it` for Italian.
'
in: header
schema:
$ref: '#/components/schemas/language'
qr_page:
name: qr-page
description: The page to place the Digital Twin QR code on. This is required when `additional-page=false`.
in: query
schema:
type: integer
prepare_scope:
name: scope
in: query
schema:
$ref: '#/components/schemas/prepare_scope'
required: true
qr_llx:
name: qr-llx
description: 'The x-coordinate of the Digital Twin QR code from the lower left corner of the document.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
qr_height:
name: qr-height
description: The height of the Digital Twin QR code. This is required when `additional-page=false`.
in: query
schema:
type: number
digital_twin:
name: digital-twin
description: Enable Digital Twin for the document.
in: query
schema:
type: boolean
default: false
additional_page:
name: additional-page
description: Whether to place Digital Twin and signatures on an additional page or inline.
in: query
schema:
type: boolean
default: true
pdf-a:
name: pdf-a
description: Enable PDF/A compatibility
in: query
schema:
type: boolean
default: false
qr_lly:
name: qr-lly
description: 'The y-coordinate of the Digital Twin QR code from the lower left corner of the document.
This is required when `additional-page=false`.
'
in: query
schema:
type: number
password_encryption:
name: password-encryption
description: The password encryption algorithm to use in encrypting the encryption key.
in: query
schema:
type: string
enum:
- xor-b58
responses:
bad_request:
description: The request is not properly formed. For example, the content could not be read.
unauthorized:
description: You are not authorized to carry out the operation. Check that your API key is correct.
securitySchemes:
api_key:
name: Authorization
in: header
type: apiKey