API reference

API overview

Send tenants, units and tenancies to Nyumbisha from your own system.

Base URL

https://api.astralyngroup.com/tenure/v1

Every path in this reference is relative to it.

Authentication

Send an OAuth 2.0 access token issued by Astralyn ID for the tenure audience. The token carries your organisation; you never send an organisation id yourself.

Authorization: Bearer <access token>

Scope	Allows
`tenure:read`	GET endpoints
`tenure:write`	POST and DELETE endpoints

Required headers

Header	When	Value
`Authorization`	every request	Bearer <token>
`Idempotency-Key`	every POST and DELETE	a new UUID per request
`Content-Type`	requests with a body	`application/json` (or `text/csv` for the import)

A POST or DELETE without Idempotency-Key is rejected with 400 idempotency_key_required.

Conventions

Money is a string of whole cents (minor units): "2500000" is KES 25,000. Never a number, never a decimal. The CSV import is the one exception: it reads amounts as a landlord types them.
Dates are YYYY-MM-DD, in Nairobi time.
Phone numbers are accepted as 0722145880, 722145880 or +254722145880, and returned as +254722145880. A phone number identifies a tenant.
Ids in paths are UUIDs, as returned in the id field.

Errors

Every error has the same body:

{
  "error": {
    "code": "unprocessable",
    "message": "We have not met this number before. What is their name?"
  },
  "request_id": "req_01J9…"
}

Status	code	Meaning
400	validation_failed	Body or query has the wrong shape. details lists each field.
400	idempotency_key_required	Missing Idempotency-Key header.
401	unauthenticated	Missing, expired or invalid token.
403	forbidden	Token lacks the scope for this endpoint.
404	not_found	No such record in your organisation.
409	conflict	The request clashes with current state, e.g. unit already let.
422	unprocessable	Well-formed, but not allowed. message says why.
5xx	internal_error	Our fault. Retry with backoff; quote request_id to support.

message is written for a person and safe to show to your users.

Endpoints

Task	Reference
Upload many tenancies from a CSV	Bulk import
Create properties and units, move one tenant in, read a tenant	Tenants