Recipes

Common API v2 tasks

Minimal happy-path examples for create, update, send, submit, export, list, and webhook setup.

Recipe 1

Create a document from a template

Create a draft document with values keyed by field name.

Find the template id.
POST /documents with name and values.
Store the returned document id.

curl -X POST https://api.crove.app/api/external/v2/documents \
  -H "X-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"<uuid>","name":"Offer letter - Ravi","values":{"Client Name":"Ravi Sharma","Project Fee":150000,"Start Date":"2026-07-01","Payment Terms":"50% upfront, 50% on delivery"}}'

const res = await fetch("https://api.crove.app/api/external/v2/documents", {
  method: "POST",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "<uuid>",
    name: "Offer letter - Ravi",
    values: {
      "Client Name": "Ravi Sharma",
      "Project Fee": 150000,
      "Start Date": "2026-07-01",
      "Payment Terms": "50% upfront, 50% on delivery"
    }
  })
});

import os, requests

res = requests.post("https://api.crove.app/api/external/v2/documents", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, json={
    "template_id": "<uuid>",
    "name": "Offer letter - Ravi",
    "values": {
        "Client Name": "Ravi Sharma",
        "Project Fee": 150000,
        "Start Date": "2026-07-01",
        "Payment Terms": "50% upfront, 50% on delivery",
    },
})

Response

{"id":"<uuid>","status":"draft","filled":12,"total":19}

What changed from v1: Values are keyed by field name; supported types include text, number, YYYY-MM-DD dates, booleans, and dropdown options.

Full schema in API reference →

Recipe 2

Update or fill values

Patch only the fields that changed.

Keep the document in draft.
PATCH /documents/{id}/values.
For Pabbly, send values[Field] or bare field keys if needed.

curl -X PATCH https://api.crove.app/api/external/v2/documents/<document_id>/values \
  -H "X-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"values":{"Special Terms":"Deliver before the filing date.","Rush Delivery":true}}'

await fetch("https://api.crove.app/api/external/v2/documents/<document_id>/values", {
  method: "PATCH",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ values: { "Special Terms": "Deliver before the filing date.", "Rush Delivery": true } })
});

requests.patch("https://api.crove.app/api/external/v2/documents/<document_id>/values", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, json={"values": {"Special Terms": "Deliver before the filing date.", "Rush Delivery": True}})

Response

{"status":"draft","filled":14,"total":19}

What changed from v1: Partial updates are supported. Pabbly flat payloads can use values[Special Terms] or a bare Special Terms key.

Full schema in API reference →

Recipe 3

Send for signature

Invite a recipient to fill or sign the document.

Prepare a filled draft.
POST /documents/{id}/send with recipients.
Use fill_url only for the intended recipient.

curl -X POST https://api.crove.app/api/external/v2/documents/<document_id>/send \
  -H "X-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"recipients":[{"email":"client@example.com","role":"Client"}]}'

await fetch("https://api.crove.app/api/external/v2/documents/<document_id>/send", {
  method: "POST",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ recipients: [{ email: "client@example.com", role: "Client" }] })
});

requests.post("https://api.crove.app/api/external/v2/documents/<document_id>/send", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, json={"recipients": [{"email": "client@example.com", "role": "Client"}]})

Response

{"sent_count":1,"recipients":[{"email":"client@example.com","role":"Client","fill_url":"https://sign.aadharsign.com/...","status":"invited"}]}

What changed from v1: Send is a dedicated v2 document action; it returns each recipient's fill URL and invite status.

Full schema in API reference →

Recipe 4

Complete without a recipient

Complete a fully filled document that does not require recipient signing.

Fill all required fields.
POST /documents/{id}/submit.
Read the document status from the response or follow-up GET.

curl -X POST https://api.crove.app/api/external/v2/documents/<document_id>/submit -H "X-Api-Key: <key>"

await fetch("https://api.crove.app/api/external/v2/documents/<document_id>/submit", {
  method: "POST",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY }
});

requests.post("https://api.crove.app/api/external/v2/documents/<document_id>/submit", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
})

Response

{"status":"completed"}

What changed from v1: Submit is separate from send; use it for no-recipient workflows.

Full schema in API reference →

Recipe 5

Export a PDF

Queue a PDF export, poll it, then download the signed URL.

POST /documents/{id}/exports with format pdf.
Poll GET /exports/{job_id}.
Download signed_download_url when status is done.

curl -X POST https://api.crove.app/api/external/v2/documents/<document_id>/exports \
  -H "X-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"format":"pdf"}'

curl https://api.crove.app/api/external/v2/exports/<job_id> -H "X-Api-Key: <key>"

const queued = await fetch("https://api.crove.app/api/external/v2/documents/<document_id>/exports", {
  method: "POST",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ format: "pdf" })
});

await fetch("https://api.crove.app/api/external/v2/exports/<job_id>", {
  headers: { "X-Api-Key": process.env.CROVE_API_KEY }
});

requests.post("https://api.crove.app/api/external/v2/documents/<document_id>/exports", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, json={"format": "pdf"})

requests.get("https://api.crove.app/api/external/v2/exports/<job_id>", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
})

Response

{"job_id":"<uuid>","status":"queued"}
{"status":"done","signed_download_url":"https://api.crove.app/api/external/v2/exports/<job>/download-signed?token=..."}

What changed from v1: Exports are async. The final signed URL returns the PDF with 200 application/pdf.

Full schema in API reference →

Recipe 6

List templates and documents

Find the template or document you need before acting on it.

Use limit and search for templates.
Filter documents by status.
Follow the full schema in the API reference for more filters.

curl "https://api.crove.app/api/external/v2/templates?limit=25&search=offer" -H "X-Api-Key: <key>"
curl "https://api.crove.app/api/external/v2/documents?status=awaiting_signature" -H "X-Api-Key: <key>"

await fetch("https://api.crove.app/api/external/v2/templates?limit=25&search=offer", {
  headers: { "X-Api-Key": process.env.CROVE_API_KEY }
});
await fetch("https://api.crove.app/api/external/v2/documents?status=awaiting_signature", {
  headers: { "X-Api-Key": process.env.CROVE_API_KEY }
});

requests.get("https://api.crove.app/api/external/v2/templates", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, params={"limit": 25, "search": "offer"})

requests.get("https://api.crove.app/api/external/v2/documents", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, params={"status": "awaiting_signature"})

Response

{"results":[{"id":"<uuid>","name":"Offer letter"}]}
{"results":[{"id":"<uuid>","status":"awaiting_signature"}]}

What changed from v1: List calls live directly under /templates and /documents in v2.

Full schema in API reference →

Recipe 7

Set up a webhook

POST /webhooks with a public HTTPS URL and canonical events.
Store the returned whsec_ secret; it is shown once.
Verify X-Crove-Signature and dedupe by payload id.

curl -X POST https://api.crove.app/api/external/v2/webhooks \
  -H "X-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/crove/webhook","events":["recipient.submitted","document.completed","export.completed","document.opened"]}'

await fetch("https://api.crove.app/api/external/v2/webhooks", {
  method: "POST",
  headers: { "X-Api-Key": process.env.CROVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/crove/webhook",
    events: ["recipient.submitted", "document.completed", "export.completed", "document.opened"]
  })
});

requests.post("https://api.crove.app/api/external/v2/webhooks", headers={
    "X-Api-Key": os.environ["CROVE_API_KEY"],
}, json={
    "url": "https://example.com/crove/webhook",
    "events": ["recipient.submitted", "document.completed", "export.completed", "document.opened"],
})

Response

{"id":"<uuid>","secret":"whsec_..."}

What changed from v1: Webhook secrets are returned once from create and rotate-secret. Store them before leaving the response.

Full schema in API reference →