Reference

Documents

List documents#

GET/documents

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Query parameters#

qstring
max length 100
statusstring
document.uploadeddocument.draftdocument.sentdocument.vieweddocument.completeddocument.declineddocument.voideddocument.expireddocument.error
tagstring
max length 50
created_fromstring (date-time) | string
created_tostring (date-time) | string
pageinteger
min 1 · max 100000 · default 1
countinteger
min 1 · max 100 · default 50
order_bystring
date_created-date_created
default "-date_created"

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

Responses#

200OKapplication/json · DocumentList
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "results": [
    {
      "id": "string",
      "name": "string",
      "status": "document.uploaded",
      "date_created": "2026-10-30T11:35:00.000000Z",
      "date_modified": "2026-10-30T11:35:00.000000Z",
      "expiration_date": "2026-10-30T11:35:00.000000Z",
      "sandbox": true
    }
  ]
}

Create a document from a PDF#

POST/documents

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

Multipart: file (PDF) and data (JSON string). Text tags such as {signature:Client} become fields (parse_text_tags, default true); AcroForm fields named Role.something become fields with parse_form_fields. Unknown role → 400.

Headers#

Idempotency-Keystring
Replays the first response for 24 hours.
max length 255

Request body#

multipart/form-data · required

filestring (binary)required
dataobjectrequired
JSON string
- namestringrequired
  min length 1 · max length 255
- recipientsarray of objectrequired
  min items 1 · max items 50
  - emailstring (email)required
    max length 254
  - first_namestring
    max length 50
  - last_namestring
    max length 50
  - rolestringrequired
    min length 1 · max length 60
  - signing_orderinteger
    min 1 · max 100
  - localestring
    enzhhiesarfrbnptidurrudejapcmarzmrviteswhatrpnbtlta
  - typestring
    signercc
- fieldsarray of object
  max items 500
  - typestringrequired
    signatureinitialsnamedatetextcheckbox
  - rolestringrequired
    min length 1 · max length 60
  - pageintegerrequired
    min 1 · max 500
  - xnumberrequired
    min 0 · max 100000
  - ynumberrequired
    min 0 · max 100000
  - widthnumberrequired
    min 0 · max 100000
  - heightnumberrequired
    min 0 · max 100000
  - requiredboolean
  - namestring
    max length 100
- parse_form_fieldsboolean
- parse_text_tagsboolean
- subjectstring
  max length 200
- messagestring
  max length 2000
- expires_in_daysany
  71430
- remindersboolean
- access_codestring
  min length 4 · max length 32
- tagsarray of string
  max items 20
- metadataobject

curl -X POST "https://macaaw.com/public/v1/documents" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F "file=@document.pdf;type=application/pdf" \
  -F 'data={"name":"string","recipients":[{"email":"client@example.com","first_name":"string","last_name":"string","role":"string","signing_order":1,"locale":"en","type":"signer"}],"fields":[{"type":"signature","role":"string","page":1,"x":0,"y":0,"width":0,"height":0,"required":true,"name":"string"}],"parse_form_fields":true,"parse_text_tags":true,"subject":"string","message":"string","expires_in_days":7,"reminders":true,"access_code":"string","tags":["string"],"metadata":{}}'

Responses#

201OKapplication/json · DocumentCreated
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
413File too largeapplication/json · Error
422Unprocessable fileapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

201 response

{
  "id": "string",
  "name": "string",
  "status": "document.uploaded",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "expiration_date": "2026-10-30T11:35:00.000000Z",
  "sandbox": true,
  "uuid": "string"
}

Document status#

GET/documents/{id}

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

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

Responses#

200OKapplication/json · DocumentStatus
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "name": "string",
  "status": "document.uploaded",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "expiration_date": "2026-10-30T11:35:00.000000Z",
  "sandbox": true
}

Delete a document now (files and records)#

DELETE/documents/{id}

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

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

Responses#

204No content
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

Document details#

GET/documents/{id}/details

Authorization: API-Key · Rate limit 300 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

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

Responses#

200OKapplication/json · DocumentDetails
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "name": "string",
  "status": "document.uploaded",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "expiration_date": "2026-10-30T11:35:00.000000Z",
  "sandbox": true,
  "date_sent": "2026-10-30T11:35:00.000000Z",
  "date_completed": "2026-10-30T11:35:00.000000Z",
  "subject": "string",
  "message": "string",
  "signing_order": "sequential",
  "silent": true,
  "recipients": [
    {
      "id": "string",
      "email": "client@example.com",
      "first_name": "string",
      "last_name": "string",
      "role": "string",
      "type": "signer",
      "signing_order": 1,
      "has_completed": true,
      "status": "waiting",
      "completed_at": "2026-10-30T11:35:00.000000Z",
      "viewed_at": "2026-10-30T11:35:00.000000Z",
      "declined_at": "2026-10-30T11:35:00.000000Z"
    }
  ],
  "fields": [
    {
      "id": "string",
      "type": "signature",
      "recipient_id": "string",
      "role": "string",
      "page": 1,
      "x": 1,
      "y": 1,
      "width": 1,
      "height": 1,
      "required": true,
      "name": "string",
      "filled": true
    }
  ],
  "tags": [
    "string"
  ],
  "metadata": {},
  "events": [
    {
      "type": "string",
      "date": "2026-10-30T11:35:00.000000Z",
      "recipient_id": "string"
    }
  ],
  "sent_by": {
    "email": "string",
    "first_name": "string",
    "last_name": "string"
  },
  "download_available": true
}

Send a draft for signature#

POST/documents/{id}/send

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

silent: true sends no emails; use embedded signing sessions. 409 unless the document is a draft.

Path parameters#

idstringrequired

Headers#

Idempotency-Keystring
Replays the first response for 24 hours.
max length 255

Request body#

application/json

subjectstring
max length 200
messagestring
max length 2000
silentboolean

curl -X POST "https://macaaw.com/public/v1/documents/$ID/send" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"string","message":"string","silent":true}'

Responses#

200OKapplication/json · DocumentStatus
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "name": "string",
  "status": "document.uploaded",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "expiration_date": "2026-10-30T11:35:00.000000Z",
  "sandbox": true
}

Remind signers#

POST/documents/{id}/remind

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

Request body#

application/json

recipient_idstring (uuid)

curl -X POST "https://macaaw.com/public/v1/documents/$ID/remind" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"string"}'

Responses#

200OKapplication/json · RemindResult
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "reminded": [
    "string"
  ],
  "skipped": [
    {
      "recipient_id": "string",
      "reason": "string"
    }
  ]
}

Void a sent document#

PATCH/documents/{id}/status

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

Request body#

application/json

status"document.voided"required
notestring
max length 500

curl -X PATCH "https://macaaw.com/public/v1/documents/$ID/status" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"document.voided","note":"string"}'

Responses#

200OKapplication/json · DocumentStatus
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "name": "string",
  "status": "document.uploaded",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "expiration_date": "2026-10-30T11:35:00.000000Z",
  "sandbox": true
}

Download the PDF#

GET/documents/{id}/download

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

Completed: the signed PDF with its signing certificate. Otherwise the original. 409 while the signed PDF is being prepared.

Path parameters#

idstringrequired

Query parameters#

separate_certificatestring
truefalse

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

Responses#

200Fileapplication/pdf · string (binary)
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

Embedded signing session#

POST/documents/{id}/session

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

For a sent document (silent or not). Open url in an iframe on one of your allowed embed origins; the page posts { type: "macaaw.signing", event: "completed"|"declined" } to the parent.

Path parameters#

idstringrequired

Headers#

Idempotency-Keystring
Replays the first response for 24 hours.
max length 255

Request body#

application/json

recipientstring (email)required
max length 254
lifetimeinteger
min 900 · max 86400

curl -X POST "https://macaaw.com/public/v1/documents/$ID/session" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"client@example.com","lifetime":900}'

Responses#

201OKapplication/json · Session
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

201 response

{
  "id": "string",
  "expires_at": "2026-10-30T11:35:00.000000Z",
  "url": "https://example.com/webhooks/macaaw"
}