Run a plan

A plan is authored and published in Keepable Workspace. The public API can discover and run it; it cannot create, edit, archive, or schedule one.

Discover the plan

GET https://api.keepable.co/sender/v2/plans?status=active&limit=50
Authorization: Bearer {{KEEPABLE_TOKEN}}

Use GET /plans/{plan_id} when you already store the id. The response describes the plan's kind, parameters, recipient model, document expectations, and current status. Run only an active plan.

Treat plan_id as configuration. Do not select a plan by display name on every request; names are for people and may change.

Run it

POST https://api.keepable.co/sender/v2/plans/pln_01J8ZQ4T/runs
Authorization: Bearer {{KEEPABLE_TOKEN}}
Idempotency-Key: 5f3c1e02-9b7a-4a11-8c2e-6d0f4b8a1c93
Content-Type: application/json

{
  "subject": "Facility FAC-2026-0118, ₦45m",
  "document_ids": ["doc_01J8ZQ4T"],
  "parameters": { "amount": 45000000 },
  "recipients": [
    {
      "addressing": { "type": "nin", "nin": "12345678901" },
      "display_name": "Musa Bello",
      "ref": "FAC-2026-0118:MUSA"
    }
  ]
}

All fields are conditional on the plan:

• parameters supplies values for declared parameter keys;
• document_ids names files uploaded through POST /documents;
• recipients is used by delivered plans, while routed plans carry their own Workspace route; and
• subject overrides a templated subject when the plan permits it.

The call returns 202 and a Correspondence. A run is not a second resource; the correspondence is the durable record from this point onward.

{
  "correspondence_id": "cor_01J8ZQ4T",
  "plan_id": "pln_01J8ZQ4T",
  "kind": "approval",
  "subject": "Facility FAC-2026-0118, ₦45m",
  "status": "live",
  "created_at": "2026-09-18T10:00:00Z"
}

Persist the correspondence_id. Reuse the same Idempotency-Key if the request times out and you retry the same logical run.

Find runs later

GET https://api.keepable.co/sender/v2/correspondence?plan_id=pln_01J8ZQ4T&limit=50
Authorization: Bearer {{KEEPABLE_TOKEN}}

Continue with Correspondence to reconcile the run and its participants.