Bulk sends API

GET /bulk_sends

List bulk sends

Every bulk send in the workspace, newest first, up to 200. The body is a bare array, not a data envelope, and takes no pagination parameters.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/bulk_sends \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /bulk_sends

Start a bulk send

Sends one or more templates to every row of a CSV. The CSV columns are <placeholder_name>_<field_label>, plus a name and email column per placeholder; fetch a matching header row from GET /bulk_sends/csv_template. The response status starts at Enqueuing while rows are turned into documents.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/bulk_sends \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q3 onboarding",
  "template_ids": [
    "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b"
  ],
  "bulk_send_csv": "U2lnbmVyX05hbWUsU2lnbmVyX0VtYWlsCkphbmUgRG9lLGphbmVAZXhhbXBsZS5jb20K",
  "skip_row_errors": false,
  "subject": "Please sign your onboarding packet",
  "message": "<p>This takes about two minutes.</p>",
  "apply_signing_order": true
}'

Example response (201)

{
  "id": "b1e2c3d4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "name": "Q3 onboarding",
  "status": "Enqueuing",
  "documents_count": 42,
  "documents_completed": 0,
  "documents_not_completed": 42,
  "test_mode": false,
  "templates": [
    {
      "id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
      "name": "Onboarding agreement",
      "status": "Available"
    }
  ],
  "created_at": "2026-09-09T17:44:10Z",
  "updated_at": "2026-09-09T17:44:10Z"
}

GET /bulk_sends/csv_template

Get a CSV template

Returns the header row for the given templates: a <Placeholder>_Name and <Placeholder>_Email column per placeholder, then one <Placeholder>_<field label> column per fillable field. Signature, initials, autofill_*, and locked date fields get no column — nothing in the CSV could fill them. The CSV form carries a UTF-8 byte-order mark so spreadsheet software opens it correctly; the base64 form does not.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/bulk_sends/csv_template \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /bulk_sends/validate_csv

Validate a bulk send CSV

Dry run. Parses the CSV against the templates and reports per-row errors without creating anything.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/bulk_sends/validate_csv \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "valid": false,
  "rows_count": 42,
  "valid_rows_count": 41,
  "row_errors": [
    {
      "row": 17,
      "column": "Signer_Email",
      "error": "is not a valid email address",
      "errors": {
        "Signer_Email": "is not a valid email address"
      }
    }
  ]
}

GET /bulk_sends/{id}

Get a bulk send

Counts and status for one bulk send, plus the templates it used.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/bulk_sends/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /bulk_sends/{id}/documents

List a bulk send's documents

The documents a bulk send produced, page by page. This is the one paginated compatibility endpoint and it uses page numbers, not cursors.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/bulk_sends/{id}/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "documents": [
    {
      "id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60",
      "status": "Sent",
      "name": "Onboarding agreement",
      "created_at": "2026-09-09T17:44:11Z"
    }
  ],
  "current_page": 1,
  "next_page": 2,
  "previous_page": null,
  "total_count": 42,
  "total_pages": 5
}