Get started

Quickstart

Create a sandbox key, upload a document, send it, receive a webhook and download the signed PDF in ten minutes.

This walk-through uses a sandbox key, so it is free on every plan and nothing you send counts against your limits. You need a PDF with a signature tag in it — any PDF whose text contains {signature:Client} works (see Text tags).

1. Create a sandbox key#

   Open Account → Developer → API keys, choose Create key, pick Sandbox and give it a name. Copy the key — it starts with mk_test_ and is shown only once. Keep it in an environment variable:

   ShellCopy

   export MACAAW_API_KEY="mk_test_…"

2. Create a document#

   Upload the PDF as file and the details as a JSON string in data. Each recipient has a role; text tags for that role become that recipient's fields.

   In the sandbox you can only send to addresses on your own email domain (or your own address if you use a public mail service such as Gmail).
   curlNode.jsPython

   Copy

   curl https://macaaw.com/public/v1/documents \
     -H "Authorization: API-Key $MACAAW_API_KEY" \
     -F "file=@contract.pdf;type=application/pdf" \
     -F 'data={"name":"Consulting agreement","recipients":[{"email":"you@yourcompany.com","first_name":"Sam","last_name":"Lee","role":"Client"}],"parse_text_tags":true}'

   The answer is 201 with status document.uploaded:

   JSONCopy

   {
     "id": "58b66391-30fa-4219-a9b3-4f7badfad583",
     "uuid": "58b66391-30fa-4219-a9b3-4f7badfad583",
     "name": "Consulting agreement",
     "status": "document.uploaded",
     "date_created": "2026-10-30T11:35:00.342000Z",
     "date_modified": "2026-10-30T11:35:00.342000Z",
     "expiration_date": null,
     "sandbox": true
   }

3. Check it is a draft#

   The file and the tags were checked during the create call, so reading the document back normally gives document.draft at once. A short poll keeps your code safe if it ever takes longer:

   curlNode.jsPython

   Copy

   curl https://macaaw.com/public/v1/documents/$DOCUMENT_ID \
     -H "Authorization: API-Key $MACAAW_API_KEY"

4. Send it#

   Sending emails each signer a link. Use "silent": true instead if you will collect signatures with embedded signing.

   curlNode.jsPython

   Copy

   curl https://macaaw.com/public/v1/documents/$DOCUMENT_ID/send \
     -H "Authorization: API-Key $MACAAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"subject": "Please sign", "message": "Hi Sam, here is the agreement."}'

5. Get a webhook#

   Add a subscription under Account → Developer → Webhooks (tick Sandbox to receive sandbox events), or through the API. Macaaw POSTs a JSON array to your HTTPS URL when the document changes state; check the signature query parameter as shown in Webhooks.

   curlNode.jsPython

   Copy

   curl https://macaaw.com/public/v1/webhook-subscriptions \
     -H "Authorization: API-Key $MACAAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Quickstart", "url": "https://example.com/hooks/macaaw", "triggers": ["document_state_changed", "document_completed_pdf_ready"], "active": true, "sandbox": true}'

6. Download the signed PDF#

   When the status is document.completed (or you receive document_completed_pdf_ready), download the signed PDF. It includes the signing certificate; sandbox output carries a “SANDBOX — NOT A VALID DOCUMENT” stamp on every page.

   curlNode.jsPython

   Copy

   curl https://macaaw.com/public/v1/documents/$DOCUMENT_ID/download \
     -H "Authorization: API-Key $MACAAW_API_KEY" \
     -o signed.pdf

Next steps#

• Embed signing in your app instead of sending emails.
• Create a live key when you are ready (needs a plan with API access).
• Browse the API reference or import the Postman collection.