Skip to content
QSign QSign Docs

Hosted USB DSC API

Use the production Envelope API when your app owns the contract workflow and QSign handles the physical USB DSC interaction. All server-to-server requests below use X-Api-Key: qsk_live_…; never expose that key in the signer’s browser. The base URL is https://app.qsig.in/backend/api/v1.

The current USB DSC envelope flow accepts one PDF and one signing recipient (CC recipients are allowed). The PDF must not already contain a cryptographic signature. Rotated or cropped pages are not supported for field placement.

1. Create a draft envelope

Section titled “1. Create a draft envelope”
Terminal window
curl -X POST 'https://app.qsig.in/backend/api/v1/envelopes' \
  -H 'X-Api-Key: qsk_live_…' -H 'Content-Type: application/json' \
  -d '{
    "title": "Services Agreement",
    "external_id": "contract-123",
    "recipients": [{
      "name": "Shubham Example",
      "email": "signer@example.com",
      "role": "signer",
      "signature_method": "dsc"
    }]
  }'

Keep the returned envelope id and signer recipients[0].id (both public UUIDs). See Create a draft envelope.

2. Attach the PDF

Section titled “2. Attach the PDF”
Terminal window
curl -X POST 'https://app.qsig.in/backend/api/v1/envelopes/<envelope-id>/documents' \
  -H 'X-Api-Key: qsk_live_…' -F 'file=@agreement.pdf;type=application/pdf'

Keep the returned document id. An existing workspace document can instead be attached by sending JSON with document_id.

3. Set the signature and other fields

Section titled “3. Set the signature and other fields”

Before sending the envelope, replace the PDF’s signer fields with PUT /envelopes/{id}/documents/{document_id}/fields. Use the signer UUID from step 1. Page numbers start at 1. Coordinates are PDF points from the top left of the page.

Terminal window
curl -X PUT 'https://app.qsig.in/backend/api/v1/envelopes/<envelope-id>/documents/<document-id>/fields' \
  -H 'X-Api-Key: qsk_live_…' -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      {"recipient_id":"<recipient-id>","field_type":1,"page_number":2,
       "x":100,"y":560,"width":180,"height":55,"label":"USB DSC signature"},
      {"recipient_id":"<recipient-id>","field_type":4,"page_number":2,
       "x":100,"y":625,"width":220,"height":30,"label":"Full name"},
      {"recipient_id":"<recipient-id>","field_type":3,"page_number":2,
       "x":100,"y":665,"width":180,"height":30,"label":"Date signed"},
      {"recipient_id":"<recipient-id>","field_type":8,"page_number":2,
       "x":100,"y":705,"width":240,"height":30,"label":"Designation",
       "value":"Authorized signatory"}
    ]
  }'

field_type: 1 is the required DSC signature. Other supported types are Date Signed (3), Full Name (4), First/Last Name (5/6), Email (7), Text (8), Checkbox (9), Number (10), Date (11), Dropdown (12) and Radio (13). Text-like values may be pre-assigned with value or entered by the signer. Name, email and signing date come from the signer details. INITIAL fields are unavailable in this DSC flow.

If the PDF already contains an empty signature field, provide its exact name instead of placement coordinates:

{
  "fields": [{
    "recipient_id": "<recipient-id>",
    "field_type": 1,
    "pdf_signature_field": "SpotDraftSignature"
  }]
}

This PUT replaces all fields on that draft PDF, so include other Name, Date or Text fields in the same request if needed. See Replace draft document fields.

4. Send and redirect the signer

Section titled “4. Send and redirect the signer”

Send the envelope with POST /envelopes/{id}/send, then create a short-lived signing session:

Terminal window
curl -X POST 'https://app.qsig.in/backend/api/v1/envelopes/<envelope-id>/signing-sessions' \
  -H 'X-Api-Key: qsk_live_…' -H 'Content-Type: application/json' \
  -d '{"recipient_id":"<recipient-id>","mode":"redirect"}'

Redirect the signer to the returned signing_url within 15 minutes. The hosted page uses QSign Agent and the token’s local driver to obtain the certificate and signature. The PIN stays on the signer’s machine. Windows and macOS token/driver combinations should be checked with a physical token during onboarding.

5. Receive completion and download

Section titled “5. Receive completion and download”

Register a webhook URL with POST /backend/othercompanyapi/webhook/save/ using your api_admin login JWT, or configure it in the Developer portal. The envelope.completed event tells your backend when the PDF is ready. Verify the timestamped HMAC signature before acting on it; see Webhooks. Then fetch the completed bytes:

Terminal window
curl -L 'https://app.qsig.in/backend/api/v1/envelopes/<envelope-id>/documents/<document-id>/download' \
  -H 'X-Api-Key: qsk_live_…' -o signed-agreement.pdf

The download is available after completion and preserves the PDF’s USB DSC signature. A 409 response means the PDF is not ready yet.