The API and webhooks

The API lets your other software read from Cartenda and send requests through it. Webhooks tell that software the moment something happens, such as a client sending documents back. Tools like Zapier, or your own scripts, use both.

Make a token#

1. Go to Settings → API. You'll be asked to confirm your password.
2. Under Tokens, click Make a token, and give it a Name that says what will use it, such as "Zapier".
3. Tick Can send requests and change clients only if the software needs to write. Leave it unticked for a read-only token.
4. Click Make token.
5. Copy the token and store it somewhere safe. This is the only time it is shown.

Send the token as a Bearer token in the Authorization header, to the base address shown on the page (it ends in /api/v1).

A token belongs to one workspace and sees only that workspace. It can read every client your workspace has, so give one only to software you trust.

The token list shows each token's name, the first characters of the token, whether it's Read only or Read and write, and when it was last used.

What the API can reach#

A read-only token can read:

• your workspace's details
• contacts, and client groups with their people
• a client group's profile: facts, what's missing, and accounts
• forms that can be sent
• requests, and submissions with their answers and document links
• documents, through short-lived download links

Drafts are never returned. A form a client has started but not sent is theirs until they send it.

A read-and-write token can also:

• find or add a contact
• start a client group
• set a profile fact, named by its key as the profile you read names it. Only your firm's client details can be set
• send a form to a contact, and say who fills the form's other roles
• subscribe and unsubscribe webhooks

Lists come back 50 items at a time. Each token can make 120 requests a minute, and sending a request through the API is held to the same limit as a person sending one.

When you send a form that names roles besides the client, you can say who fills each one. Leave that out and the client's spouse or partner is filled from their client group, as a send from Cartenda fills it; send an empty list and the client answers every role. Each person needs an email address, or a cell number already confirmed for texts. A request you read back lists everyone on it and how far each has got, never their answers.

A form that delivers a document filled with a client's Social Security number can't be sent through the API. Sending one asks a person to confirm their password first, so send it from Cartenda. A form that delivers any other PDF filled for a client can be sent through the API only to someone in the client group it was filled for.

Add a webhook#

1. On Settings → API, under Webhooks, click Add a webhook and enter the URL that should receive events.
2. Under Events, tick the ones you want:
   • request.sent: a request went out to a client.
   • submission.received: a client sent something back.
   • submission.completed: your firm marked a submission complete.
   • profile.updated: a client's profile changed.
   • signing.completed: everyone who had to sign a submission has signed.
3. Click Add webhook. Copy the signing secret that's shown. Like a token, it's shown only once.

Click Send test beside a webhook to send it a ping event.

Check a webhook is genuine#

Each event is sent as a JSON POST with a Cartenda-Signature header in the form t=<time>,v1=<signature>. The signature is an HMAC-SHA256 of the time, a period and the raw body, keyed with the webhook's secret. Refuse a message whose signature doesn't match, or whose time is more than five minutes old.

The Cartenda-Delivery header carries the same ID on every attempt, so your receiver can ignore a repeat.

When a delivery fails#

If your URL doesn't answer with a 2xx response, Cartenda tries again after 1, 5, 15 and 60 minutes, about an hour and a half in all. After that, the delivery is left as failed.

Recent deliveries on the API page shows each one as Delivered, Failing or Queued, with the response code or error.

Revoke a token#

Click Revoke beside a token. Anything using it stops working straight away, and the webhooks it set up are turned off. Webhooks added through the API show which token added them.

To remove a webhook you added on the page, click Remove, then Remove webhook to confirm. If you add it again later, it gets a new signing secret.

When somebody leaves the workspace, is removed, or moves to a role that can't make tokens, the tokens they made are revoked and the webhooks they added are turned off.

Who can use the API page#

Opening Settings → API is for people who can change workspace settings. Making a token also needs permission to export client data, because a token can read every submission and document. By default, both mean owners and admins.