Tenants

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 rarely call these endpoints. Creating one is idempotent and bound to your identity: a credential maps to exactly one tenant (its id is derived from your organisation, not chosen by you), so POST /sender/tenants provisions your tenant on the first call and returns that same tenant thereafter. To act on behalf of other organisations, use access delegation. Tenant reads need tenant.read; writes need tenant.write.

Create (or fetch) your tenant

curl https://api.keepable.co/sender/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": [] }

This call is idempotent: the first call returns 201 with your new tenant, and any repeat returns 200 with the same tenant, unchanged. You don't choose the tenant_id; it's derived from your organisation.

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/sender/tenants/ten_01HXP \
  -H "Authorization: Bearer $KEEPABLE_TOKEN" \
  -H "Keepable-Version: 2026-05-24"

# Rename
curl -X PUT https://api.keepable.co/sender/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/sender/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. These record your organisation's own tax identity as a sender, and are how a tenant is found in the tenant-list filter (the tin_number query above).

# Attach a TIN
curl https://api.keepable.co/sender/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/sender/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/sender/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, and ≤ 1 MB. A file that breaks those rules returns 422 Unprocessable Entity. A successful upload returns 204 No Content. A transparent background is recommended (so the icon sits cleanly on any inbox surface) but not required.