Skip to content
Signkoi
Developer docs

Quickstart

Create an API key, make your first request, send an envelope for signature and get notified by webhook — in about ten minutes.

On this page

You will need a Signkoi account (the free plan works) and a PDF to send. Every example uses an environment variable for the key, so set it once in your shell.

1. Create an API key

  1. Sign in and open Developer → API keys.
  2. Choose Create key, give it a name (for example “Quickstart”) and keep Full access for this tutorial.
  3. Copy the key straight away — it is shown only once.
Shell
export SIGNKOI_API_KEY="paste-your-key-here"

Keep keys on your server

An API key acts as you. Never put it in browser or mobile app code, and never commit it to a repository.

2. Make your first request

GET/v1/me returns the account the key belongs to and the key's scopes — a quick way to check that authentication works.

curl https://signkoi.com/api/v1/me \
  -H "Authorization: Bearer $SIGNKOI_API_KEY"
200 · application/json
{
  "object": "account",
  "id": "1842",
  "name": "Rina Koh",
  "email": "rina@acme.example",
  "locale": "en",
  "timezone": "Europe/London",
  "api_key": {
    "id": "311",
    "name": "CRM integration",
    "scopes": [
      "envelopes:read",
      "envelopes:write",
      "account:read"
    ],
    "expires_at": null
  },
  "plan": "pro",
  "usage": {
    "documents_this_period": 37,
    "document_limit": 200
  }
}

A 401 means the key is missing or wrong; see Authentication.

3. Send an envelope

One request uploads the PDF, adds the signer and sends the invitation. Without explicit fields, Signkoi places a signature box on the last page for the first signer; the envelopes guide shows how to place fields yourself. Upload the file as multipart (curl, Python, PHP) or inline as base64 in JSON (Node).

curl https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@agreement.pdf \
  -F title="Consulting agreement" \
  -F 'recipients=[{"name":"Maya Patel","email":"maya@example.com"}]' \
  -F 'metadata={"crm_deal_id":"D-10492"}' \
  -F send=1

The response is the envelope with status: "sent". Maya gets an email with a secure link — she signs in any browser, no account needed. The Idempotency-Key makes the request safe to retry: if the connection drops and you send it again with the same key, you get the original response instead of a second envelope (see Idempotency).

Counts against your plan

Envelopes created through the API use your monthly document allowance like uploads on the website. When it is used up the API answers 402 with code plan_limit.

4. Track it

Retrieve the envelope with GET/v1/envelopes/{id} to see its status and each recipient's progress, or list envelopes with filters using GET/v1/envelopes.

curl -G https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  --data-urlencode "status=sent" \
  --data-urlencode "metadata[crm_deal_id]=D-10492"

Once everyone has signed, status becomes completed and files.signed and files.certificate link to the sealed PDF and the certificate of completion.

5. Get notified by webhook

Instead of polling, register an HTTPS endpoint with POST/v1/webhooks. Save the secret from the response: you need it to verify signatures.

curl -X POST https://signkoi.com/api/v1/webhooks \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/signkoi",
    "events": [
      "envelope.completed",
      "envelope.declined",
      "recipient.completed"
    ]
  }'

Then send yourself a signed test event with POST/v1/webhooks/{id}/test.

Where to go next