DKBSignDocs

API reference

POSTRequires Bearer token

Qualified signature with a one-shot certificate

/api/v4/sign/qualified

Sign one PDF for a person the customer has already identified. Call POST /api/v4/sign/qualified/otp first and send the code back as payload.otp_code. The API checks it before issuing a short-lived personal certificate, signs, then destroys the private key.

Multipart only.

  • file: the PDF (max 10 MB)
  • payload: JSON string
  • signature_image: optional PNG or JPEG (max 2 MB). Used only on marks whose type is signature. A signature mark is still applied when this file is omitted.

payload.signer: first_name, last_name, email, phone, and reason are required. reason is the signature reason stored in the PDF (max 500 characters). id_card.document_type is cni or passport. id_card.document_number is required.

payload.params.pages places the marks. x and y are in millimetres. width and height are the box size in points. type is signature (default), initials, or text. A text mark also takes text (the words drawn in the box, max 500 characters). A mark may use anchor alone (text already printed in the PDF, for example {{signature}}) instead of x and y. The signature is centered on that text and covers it. page limits the anchor search. occurrence keeps one match.

The level is always qualified. There is no signing link. The signature is refused until payload.otp_code matches the code sent to that signer. The response only returns the masked last 4 digits of the ID number.

Path parameters

This endpoint has no path parameters.

Query parameters

This endpoint has no query parameters.

Request body

Send as multipart/form-data.

FieldTypeDescription
file
Required
filePDF to sign (max 10 MB).
signature_image
stringOptional PNG or JPEG appearance (max 2 MB) for marks of type signature. Omitted: the signature is still applied.
payload
Required
objectJSON string. See nested payload.* fields.
e.g. {"otp_code":"123456","signer":{"first_name":"Awa","last_name":"Koné","email":"awa.kone@example.com","phone":"+2250700000000","reason":"Acceptation du contrat","id_card":{"document_type":"cni","document_number":"CI123456789"}},"params":{"pages":[{"page":0,"signatures":[{"anchor":"{{signature}}","width":200,"height":70,"type":"signature"},{"x":20,"y":40,"width":180,"height":40,"type":"text","text":"Lu et approuvé"}]}]}}

Responses

StatusMeaning
200See the example response.
401Missing or invalid Bearer token.

Request

curl
curl -X POST 'https://api.dkbsigns.com/api/v4/sign/qualified' \
  -H 'Authorization: Bearer $DKBSIGN_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=@./document.pdf' \
  -F 'signature_image=signature_image' \
  -F 'payload={"otp_code":"123456","signer":{"first_name":"Awa","last_name":"Koné","email":"awa.kone@example.com","phone":"+2250700000000","reason":"Acceptation du contrat","id_card":{"document_type":"cni","document_number":"CI123456789"}},"params":{"pages":[{"page":0,"signatures":[{"anchor":"{{signature}}","width":200,"height":70,"type":"signature"},{"x":20,"y":40,"width":180,"height":40,"type":"text","text":"Lu et approuvé"}]}]}}'

Response 200

json
{
  "message": "Document signé avec succès",
  "document_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "signed_pdf_url": "https://api.example.com/api/v4/documents/550e8400-e29b-41d4-a716-446655440000/download",
  "verification_url": "https://api.example.com/api/v4/verify/550e8400-e29b-41d4-a716-446655440000",
  "signer": {
    "email": "awa.kone@example.com",
    "reason": "Acceptation du contrat",
    "id_card": {
      "document_type": "cni",
      "document_number_masked": "CI••••6789"
    }
  },
  "certificate": {
    "serial": "01AB",
    "expires_at": "2026-10-09T15:00:00"
  }
}