Getting started

Environments

Every example uses a bearer access token issued by Camel Accounts. Do not use an ID token or a phone/password value as the API credential. Keep access tokens out of source control and logs.

1. Start the API locally

From the Simamia repository root:

cd api
go run .

The service listens on port 8080; PORT changes the port. The default database path is data/simamia.db relative to the process working directory. Set SIMAMIA_DB_PATH to choose another location.

2. Check health

Health is public and does not need an access token:

curl --include http://localhost:8080/api/v1/health

Expected data includes service simamia-api, API version v1, timezone Africa/Dar_es_Salaam, and currency TZS.

3. Set request variables

Use a short-lived token from an authenticated Camel Accounts session. The placeholder below is deliberately fake:

export SIMAMIA_API='http://localhost:8080/api/v1'
export SIMAMIA_TOKEN='replace-with-a-Camel-Accounts-access-token'

List the authenticated account’s customers:

curl --include "$SIMAMIA_API/customers?page=1&page_size=20" \
  -H "Authorization: Bearer $SIMAMIA_TOKEN" \
  -H 'Accept: application/json'

If Camel Accounts cannot be reached, a data request may return 503 AUTH_UNAVAILABLE. If the token is missing, invalid, or expired, it returns 401 UNAUTHORIZED.

4. Create your first records

Create a customer first. Then use its display name on the order; the current API stores the customer as a name string rather than a customer foreign key.

curl --include -X POST "$SIMAMIA_API/customers" \
  -H "Authorization: Bearer $SIMAMIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Asha Mushi","phone":"+255 712 345 678","location":"Kinondoni, Dar es Salaam"}'

Create a service before using it in an order:

curl --include -X POST "$SIMAMIA_API/services" \
  -H "Authorization: Bearer $SIMAMIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Wash and fold","category":"Laundry","duration":"24 hours","price":25000}'

Then create an order:

curl --include -X POST "$SIMAMIA_API/orders" \
  -H "Authorization: Bearer $SIMAMIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"customer":"Asha Mushi","phone":"+255 712 345 678","service":"Wash and fold","date":"2026-10-12T09:00:00+03:00","amount":25000,"status":"New","paid":0,"method":"Not paid","assignee":"Owner"}'

Record IDs are generated by the server. Use the created response’s data.id in follow-up requests.

5. Create a Simamia business profile

POST /businesses stores the business profile created during app onboarding. The API currently accepts a JSON object without resource-specific required fields. Use your template ID in primaryTemplate and include a version for later workflow migrations.

curl --include -X POST "$SIMAMIA_API/businesses" \
  -H "Authorization: Bearer $SIMAMIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"businessName":"Amani Laundry","phone":"+255712345678","primaryTemplate":"laundry","templateVersion":1}'

Request conventions

• Send JSON with Content-Type: application/json for POST and PATCH.
• Send the access token in Authorization: Bearer <token> on every data request.
• You may send X-Request-ID to correlate a call with your logs. The API creates a request ID if omitted and returns it in both the response header and meta.request_id.
• Monetary values are positive numeric amounts in Tanzanian shillings (TZS), unless the field is an amount already paid, which may be zero.
• Request bodies are limited to 1 MiB and must contain exactly one JSON object.
• Collection pages default to page=1&page_size=20; requested page sizes above 100 are capped at 100.

Continue with authentication, the shared API behavior, or the complete workflow walkthrough.