Import from another system

The simplest way: export a CSV

Every property system can export tenants to a spreadsheet. Export one row per occupied unit with the columns in the spreadsheet guide, and import it the same way. Nyumbisha does not take database dumps (.sql files) directly; a query like this one, run on your own database, produces the file:

SELECT b.name        AS "Property",
       u.door_number AS "Unit",
       u.account_ref AS "Unit Code",
       t.full_name   AS "Tenant Name",
       t.phone       AS "Phone",
       l.rent        AS "Rent",
       l.deposit     AS "Deposit",
       l.start_date  AS "Start Date",
       l.balance     AS "Balance"
  FROM leases l
  JOIN units u     ON u.id = l.unit_id
  JOIN buildings b ON b.id = u.building_id
  JOIN tenants t   ON t.id = l.tenant_id
 WHERE l.active;

Your table and column names will differ; the headings on the left are what matter.

The import API

The same import is an HTTP endpoint, for systems that want to send tenancies without a person in the middle. It takes the CSV as a string and answers with a report per row.

POST /tenure/v1/import/tenancies?dry_run=true
Authorization: Bearer <access token>
Idempotency-Key: <a new UUID per attempt>
Content-Type: application/json

{ "csv": "Property,Unit,Tenant Name,Phone,Rent\nRiverside Court,B12,Faith Wafula,0722145880,25000" }

200 OK
{
  "dryRun": true,
  "totalRows": 1,
  "imported": 0,
  "alreadyImported": 0,
  "failed": 0,
  "rows": [{ "line": 2, "outcome": "imported", "unitLabel": "B12", "tenantName": "Faith Wafula" }]
}

• dry_run defaults to true: nothing is written until you send dry_run=false. Check the report first.
• Sending the same rows again is safe. Units are recognised by their code and tenancies by their unit and dates, and are reported as already_imported.
• Every row that cannot be imported comes back with outcome: "failed" and a problem written for a person.

Full request and response fields, errors and the single-tenant endpoints are in the API reference.