DKBSignDocs

API reference

POSTRequires Bearer token

Create a signing envelope

/api/v4/envelopes

Batch of documents plus an ordered list of signers. Multipart: documents[] (PDFs, max 10 MB each) and a JSON string payload. Attachments: attachments_{idx}[] (max 15 MiB each), where idx is the document index.

payload fields:

  • title, message
  • signing_order: ordered (default) or any
  • signature_level: simple, advanced (default when omitted), qualified
  • signers[]: name, first_name, email, phone, priority, positions
  • positions keys are document indexes ("0", "1", …). Each mark: page, x, y (mm), optional width/height, type. Or anchor alone: text printed in the PDF, no x/y. The signature is centered on that text and covers it.
  • optional password: { enabled, user_password, owner_password } (user_password min 4)

Each signer in the 201 response includes uuid, signing_url, and optionally dev_otp_code in test mode.

Path parameters

This endpoint has no path parameters.

Query parameters

This endpoint has no query parameters.

Request body

FieldTypeDescription
documents
Required
arrayPDFs to sign (max 10 MB each).
e.g. ["example"]
payload
Required
objectJSON string (multipart) with envelope metadata and signers. See nested payload.* fields.
e.g. {"title":"NDA Q1","message":"Please sign","signing_order":"ordered","signature_level":"advanced","signers":[{"name":"Dupont","first_name":"Jean","email":"jean@example.com","phone":"+2250700000001","priority":1,"positions":{"0":[{"page":0,"x":120,"y":200,"width":200,"height":70,"type":"signature"}]}}]}
attachments_0
arrayOptional attachments for document index 0 (repeat attachments_{idx}).

Responses

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

Request

curl
curl -X POST 'https://api.dkbsigns.com/api/v4/envelopes' \
  -H 'Authorization: Bearer $DKBSIGN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"documents":["example"],"payload":{"title":"NDA Q1","message":"Please sign","signing_order":"ordered","signature_level":"advanced","signers":[{"name":"Dupont","first_name":"Jean","email":"jean@example.com","phone":"+2250700000001","priority":1,"positions":{"0":[{"page":0,"x":120,"y":200,"width":200,"height":70,"type":"signature"}]}}]}}'

Response 201

json
{
  "message": "Parapheur créé et prêt pour la signature",
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "NDA Q1",
  "signers": [
    {
      "uuid": "signer-uuid",
      "email": "jane@acme.test",
      "signing_url": "https://app.example/sign/signer-uuid",
      "status": "pending"
    }
  ]
}