Organisations

Create, list, rename and delete Organisations under /v1/orgs.

These are the endpoints the portal calls to manage Organisations. They accept a signed-in person's session only. Any other credential gets 403:

Credential	`error`
Personal API key	`session_required`
Organisation Key	`not_available_for_organisation_key`
Tenant token	`not_available_for_tenant`

A person who is not a member of the Organisation gets 404 not_found, so the routes never confirm that an Organisation exists. A member without the role a route needs gets 403 forbidden.

The Organisation object

An OrganisationJSON

{
  "orgId": "org_3f9a1c0b7e2d4a6f8c10",
  "name": "Acme Health",
  "status": "active",
  "role": "owner",
  "createdAt": 1790000000000
}

Field	Notes
`orgId`	Sai's id for the Organisation.
`name`	1 to 100 characters. Names are not unique.
`status`	`active` or `disabled`. A disabled Organisation can still be read, but every change, every Tenant token and every Organisation Key is refused with `403 organisation_disabled`. Contact support@simular.ai.
`role`	Your role in it: `owner` or `admin`. See Members.
`createdAt`	Unix time in milliseconds.

Create an Organisation

Anyone signed in. You become its owner.

Create an OrganisationcURL

curl -s "$SAI_API_URL/v1/orgs" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Health" }'

Field	Type	Required	Notes
`name`	string	yes	1 to 100 characters.

201 Created · OrganisationJSON

{
  "orgId": "org_3f9a1c0b7e2d4a6f8c10",
  "name": "Acme Health",
  "status": "active",
  "role": "owner",
  "createdAt": 1790000000000
}

Status	`error`	When
`400`	`invalid_body`	`name` is missing or out of range.
`403`	`phone_verification_required`	A free account has not verified a phone number, as for an API key.
`422`	`organisation_limit_reached`	You already created 5 Organisations.
`429`	`rate_limited`	More than 5 Organisations created in an hour.

List your Organisations

Anyone signed in. Lists every Organisation you are a member of, with your role in each.

List your OrganisationscURL

curl -s "$SAI_API_URL/v1/orgs" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

200 OK · OrganisationsJSON

{
  "organisations": [
    {
      "orgId": "org_3f9a1c0b7e2d4a6f8c10",
      "name": "Acme Health",
      "status": "active",
      "role": "owner",
      "createdAt": 1790000000000
    }
  ]
}

Get an Organisation

Owner or admin.

Get an OrganisationcURL

curl -s "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

200 with the Organisation, or 404 not_found.

Rename an Organisation

Owner only.

Rename an OrganisationcURL

curl -s -X PATCH "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Health Group" }'

Field	Type	Required	Notes
`name`	string	yes	1 to 100 characters.

200 with the renamed Organisation.

Status	`error`	When
`403`	`forbidden`	You are an admin, not an owner.
`403`	`organisation_disabled`	The Organisation is disabled.
`404`	`not_found`	No such Organisation, or not yours.

Delete an Organisation

Owner only. Every Tenant must be deleted first.

Delete an OrganisationcURL

curl -s -X DELETE "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

204 No Content. Deleting an Organisation removes its keys, members and pending invitations. Unspent credit is lost.

While any Tenant exists, active or disabled, the delete returns 409 and lists them, at most 100, with more set when there are others:

409 Conflict · organisation_has_tenantsJSON

{
  "error": "organisation_has_tenants",
  "message": "Delete every Tenant before deleting the Organisation.",
  "tenants": [{ "tenantId": "Xk2p9QzR4tLm8vNa3bCd", "name": "Riverside Clinic" }],
  "more": false
}

Status	`error`	When
`403`	`forbidden`	You are an admin, not an owner.
`403`	`organisation_disabled`	The Organisation is disabled.
`404`	`not_found`	No such Organisation, or not yours.
`409`	`organisation_has_tenants`	The Organisation still has Tenants.