Tenants
A tenant is your organisation inside Keepable, the entity that owns content, agreements, forms, and branding. Create and manage tenants, attach TINs, and set the icon recipients see.
A tenant is your organisation as Keepable sees it: the entity that owns the
content you send, the agreements you run, the forms you publish, and the branding
recipients see next to your mail. Almost every Sender API path is scoped under a
tenant_id, so a tenant is the first thing you need.
Most integrators are provisioned a tenant during onboarding and never call these
endpoints. They matter when you manage many organisations programmatically:
a payroll platform onboarding employers, say. Tenant reads need tenant.read;
writes need tenant.write.
Create a tenant
curl https://api.keepable.co/tenants \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "Lagos State IRS" }'{ "tenant_id": "ten_01HXP", "name": "Lagos State IRS", "company_ids": [] }The new tenant's id is also returned in a keepable-tenant-key response header.
Hold onto the tenant_id: it goes in the path of every subsequent call for this
organisation.
Read and update
# Fetch one
curl https://api.keepable.co/tenants/ten_01HXP \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24"
# Rename
curl -X PUT https://api.keepable.co/tenants/ten_01HXP \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "Lagos State Internal Revenue Service" }'List tenants with pagination, optionally filtering by an attached TIN:
curl "https://api.keepable.co/tenants?tin_number=12345678-0001&limit=50" \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24"{
"tenants": [
{ "tenant_id": "ten_01HXP", "name": "Lagos State IRS", "company_ids": ["12345678-0001"] }
],
"next_token": null
}Company IDs (TINs)
A tenant can have one or more TINs (Tax Identification Numbers) attached,
its company_ids. A TIN is what lets other organisations address this tenant as
a company recipient via TIN matching, and is
how you are found in a tenant list filter.
# Attach a TIN
curl https://api.keepable.co/tenants/ten_01HXP/company_ids \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "tin_number": "12345678-0001" }'
# Detach a TIN
curl -X DELETE "https://api.keepable.co/tenants/ten_01HXP/company_ids?tin_number=12345678-0001" \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24"Both return 204 No Content. Attaching a TIN already held by another tenant
returns 409 Conflict: a TIN belongs to
exactly one tenant.
Branding: the tenant icon
Recipients see your icon next to every item you send. Upload it as
multipart/form-data:
curl -X POST https://api.keepable.co/tenants/ten_01HXP/icon \
-H "Authorization: Bearer $KEEPABLE_TOKEN" \
-H "Keepable-Version: 2026-05-24" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@icon.png"The icon must be a PNG, square, 256–512 px, ≤ 1 MB, with an alpha
channel (transparent background). A file that breaks those rules returns
422 Unprocessable Entity. A
successful upload returns 204 No Content.
The icon is the most visible piece of your brand inside the recipient inbox. A transparent-background PNG that reads cleanly at small sizes (it renders as small as the list avatar) is worth getting right.
Forms
Publish reusable form templates that recipients fill in from their inbox, then read the responses back. Covers field types, template lifecycle, and collecting responses.
Access delegation
Let one tenant act on behalf of another. Request access to a tenant, and accept or reject requests targeting yours.