DKBSignDocs

API reference

POSTRequires Bearer token

Self-sign documents

/api/v4/sign

Apply the connected user’s certificate to one or more PDFs (max 100, 10 MB each).

Multipart: file (single) or files[], plus a JSON string params. Optional metadata / metadata[], signature_image, attachments[] / attachments_{index}[], signers_csv.

JSON: { "data"|"url", "filename", "params" } or { "documents": [...], "params" }.

params.pages places marks in millimetres. Types: signature, initials, seal, qrcode, date, text, approval. signature_level is simple, advanced (historical default), or qualified.

A mark may set anchor instead of x and y. anchor is text already printed in the PDF (for example {{signature}}). The API finds every match, centers the signature on that text, and covers the printed placeholder. page limits the search to one page. occurrence (0-based) keeps a single match. The printed text must be extractable, and it must match exactly.

When OTP is required send otp_code inside params. Qualified + TOTP: mfa_code. Qualified + email fallback: second_otp_code.

400 PDF_TOO_LARGE when a PDF exceeds 10 MB. 400 ANCHOR_NOT_FOUND when that text is missing. Multi-document partial success is 207. Quota / level errors are 403. Qualified timestamp outage is 503 TIMESTAMP_UNAVAILABLE_RETRY.

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
stringSingle PDF (multipart, max 10 MB).
files
arrayMultiple PDFs (multipart, max 100, 10 MB each).
params
Required
objectJSON object (or JSON string in multipart). Required. See nested params.* fields.
e.g. {"pages":[{"page":0,"signatures":[{"x":120,"y":200,"width":200,"height":70,"type":"signature"}]}],"signature_level":"advanced"}
metadata
objectOptional metadata (single document).
signature_image
stringPNG/JPG, max 2 MB.
data
stringBase64 PDF when sending JSON (required with filename if not using url / documents).
e.g. "JVBERi0xLjQ="
url
stringRemote PDF URL when sending JSON (alternative to data).
e.g. "https://files.acme.test/contract.pdf"
filename
stringFile name when sending JSON.
e.g. "contract.pdf"
documents
arrayJSON multi-document payload (data or url plus filename per item).
e.g. [{"data":"JVBERi0xLjQ=","filename":"contract.pdf"}]

Responses

StatusMeaning
200Single document
401Missing or invalid Bearer token.

Request

curl
curl -X POST 'https://api.dkbsigns.com/api/v4/sign' \
  -H 'Authorization: Bearer $DKBSIGN_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=file' \
  -F 'files=files' \
  -F 'params={"pages":[{"page":0,"signatures":[{"x":120,"y":200,"width":200,"height":70,"type":"signature"}]}],"signature_level":"advanced"}' \
  -F 'metadata={}' \
  -F 'signature_image=signature_image' \
  -F 'data=JVBERi0xLjQ=' \
  -F 'url=https://files.acme.test/contract.pdf' \
  -F 'filename=contract.pdf' \
  -F 'documents=[object Object]'

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