Skip to content
Browse developers

Getting started

Create a key, make your first call, and send an envelope for signature over the API.

Last updated

Everything runs against https://cecursign.io/api/v1, over HTTPS, with one header. Four requests take you from a PDF on disk to a signing link in a client's inbox: upload the document, create the envelope, place the fields, send it.

What you need

A CecurSign account on the Business plan, and a key. Keys are created in the application, at Settings > Developer > API keys, by an owner or an administrator. The key is displayed once, at the moment it is created, so copy it into your configuration before you close the dialog.

Every request carries it as a bearer token:

Authorization: Bearer cs_prod_...

There is no client library to install and no token exchange to perform. Authentication covers permissions, expiry and how to record which member of staff a call is acting for.

Check the key works

curl https://cecursign.io/api/v1/openapi.json \
  -H "Authorization: Bearer cs_prod_..." \
  -o cecursign-openapi.json

That is the OpenAPI 3 document for the whole API, served by the same process that serves the routes, so it describes exactly the deployment you just called. Any key with READ may fetch it, and it is what to generate a typed client from. The browsable version is the API reference.

Send a document for signature

1. Upload the document

curl -X POST https://cecursign.io/api/v1/documents \
  -H "Authorization: Bearer cs_prod_..." \
  -F "file=@engagement-letter.pdf" \
  -F "name=Engagement letter"

{
  "id": "9c1f1f2a-1f2b-4a3c-9d4e-5f6a7b8c9d01",
  "name": "Engagement letter",
  "status": "PROCESSING",
  "message": "Document uploaded successfully. Processing in progress."
}

A file larger than we accept is refused with 413.

Page counting and rendering happen in the background. Poll GET /v1/documents/{id} until status is READY before you place fields, because a field position is relative to a page. A file we cannot process reaches ERROR instead, so treat that as a terminal state rather than polling on.

2. Create the envelope

curl -X POST https://cecursign.io/api/v1/envelopes \
  -H "Authorization: Bearer cs_prod_..." \
  -H "X-Acting-User: jane@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Please sign: engagement letter",
    "message": "Please review and sign at your convenience.",
    "documentIds": ["9c1f1f2a-1f2b-4a3c-9d4e-5f6a7b8c9d01"],
    "recipients": [
      { "email": "client@example.com", "name": "Alex Byrne", "role": "SIGNER", "order": 1 }
    ]
  }'

subject is required and capped at 255 characters, documentIds needs at least one document, and recipients needs at least one entry with role: "SIGNER". A recipient also accepts order, authMethod, accessCode, recipientRole and redirectUrl. The envelope itself accepts signingOrder, expiresAt, folderId, departmentId, templateId and a free-form metadata object.

X-Acting-User is required here. An envelope records who created it, an API key is not a person, and the name goes on the email that carries the document. Send a CecurSign user id or the email address of a colleague in the same account.

The response carries the new envelope's id, in status DRAFT.

3. Place the fields

curl -X POST "https://cecursign.io/api/v1/documents/9c1f1f2a-1f2b-4a3c-9d4e-5f6a7b8c9d01/fields/bulk?envelopeId=3b7d0e11-4c22-4f8a-9a1e-8d2c4b5e6f70" \
  -H "Authorization: Bearer cs_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      { "pageNumber": 1, "x": 0.1, "y": 0.75, "width": 0.3, "height": 0.06, "type": "SIGNATURE", "label": "Signature", "required": true },
      { "pageNumber": 1, "x": 0.55, "y": 0.75, "width": 0.2, "height": 0.04, "type": "DATE", "label": "Date signed" }
    ]
  }'

This step is not optional. Sending refuses an envelope with no fields, and refuses one whose fields are all optional, so at least one field must be required (which is the default).

pageNumber counts from 1. x, y, width and height are fractions of the page between 0 and 1, measured from the top left corner, so a field stays where you put it whatever the page size. recipientRole assigns a field to a particular signer; label and placeholder are what the signer sees.

The envelopeId query parameter is what ties the placements to this send. A document can be reused across many envelopes, and its fields belong to the envelope or template that owns them rather than to the document.

4. Send it

curl -X POST https://cecursign.io/api/v1/envelopes/3b7d0e11-4c22-4f8a-9a1e-8d2c4b5e6f70/send \
  -H "Authorization: Bearer cs_prod_..." \
  -H "X-Acting-User: jane@example.com" \
  -H "Idempotency-Key: engagement-letter-4417"

The body is optional and takes only expiresAt. The response reports how many recipients were notified and returns a signing link per recipient, which you can surface in your own interface instead of relying on our email.

Listing envelopes, and the one default that will surprise you

GET /v1/envelopes returns envelopes composed and sent through the app. Two other kinds exist and neither is in that answer unless you ask:

  • PROPOSAL_ACCEPTANCE, spawned when a client accepts a proposal and signs the engagement letter.
  • SELF_SIGN, a document the sender signed alone and never sent to anybody.

Pass source=PROPOSAL_ACCEPTANCE or source=SELF_SIGN for one of them, or includeAll=true for every kind at once. source wins where both are given. The same two parameters apply to the list statistics.

Every envelope carries source in its response, on the list as well as the detail, so provenance is readable without a second call. A PROPOSAL_ACCEPTANCE row also carries proposalId and, where the row is new enough to have been stamped with one, proposalRef. Render provenance from source and treat the reference as a bonus.

Metering follows the same line: only DIRECT envelopes count against the monthly envelope allowance.

Next

Send the same Idempotency-Key again if a request times out and you need to retry: Idempotency. Learn the refusals before you meet them: Errors. Pace yourself against the two ceilings: Rate limits. And rather than polling for the outcome, subscribe to Webhooks, which tell you the moment the envelope is viewed, signed, declined or completed.