Connect other apps with the API and webhooks

1. Open API settings

   Go to API settings in your account.

2. Click Create key

   Give it a name you will recognize later, such as the app it is for, then choose Read and send or Read.

3. Copy the key

   Inkly shows it once. Store it where your server keeps its other secrets, never in website code or a shared document.

The simplest way is from a template, since the fields are already placed. List your templates with GET /templates, and get the roles to fill with GET /templates/{id}. Then send it:

curl -X POST "https://www.inkly.so/api/v1/documents" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "recipients": [
      { "role_id": "ROLE_ID", "name": "Alex Morgan", "email": "alex@example.com" }
    ]
  }'

The Idempotency-Key is any unique value you choose. If a request times out, retry with the same value and you will not send the document twice.

To send a PDF that is not a template, there are three requests:

1. Start the upload with POST /uploads

   You get back an upload_id and an upload_url that works for one hour.

2. Upload the file

   Upload the PDF

   curl -X PUT "$upload_url" \
     -H "Content-Type: application/pdf" \
     --data-binary @document.pdf

3. Send it with POST /documents/from-upload

   List the recipients and place each field by page and position. The API reference has a full example.

   Or skip the measuring: add a small white marker such as {{signature;signer=client}} to the PDF where the field belongs, and send use_markers as true. Inkly never changes your PDF, and refuses the send if a marker is wrong. See field markers for the rules.

1. Click Add endpoint on API settings

   Enter your server's HTTPS address and choose which events you want, such as a document being completed.

2. Copy the signing secret

   It starts with whsec_. Your server uses it to check that a webhook really came from Inkly.

3. Verify every webhook

   Accept a webhook only if its signature matches and it is under 5 minutes old, and check the raw body before any JSON parsing. Any Standard Webhooks library does this, and the API reference has a Node.js example you can copy.

4. Skip duplicates

   The same event can arrive more than once, and events can arrive out of order. Save each webhook-id header you have handled and ignore repeats. It stays the same on every retry.

5. Open the endpoint and click Send test event

   Check that your server answers with a 2xx within 10 seconds. The endpoint's delivery log shows the result.

The API and webhooks reference covers every endpoint, error code, limit, and webhook event.