Managing Teams

A Team is an Account. These endpoints let you provision a Team, read it back, update its settings and remove it. All are API-key authenticated (HTTP Basic).

Fields inferred from your API key

Your API key identifies the organization and the acting user. You do not send credentials in the body — and the account creator defaults to the user behind the key when you omit user_id.

Discover your Teams

Fetch the profile for a user to see every Team they belong to, their roles, and the organizations in scope. Use this to enumerate the Teams available to your integration.

curl "$PH_BASE_URL/api/v2/user_profile/42" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD"

GET /api/v2/user_profile/{user_id}

200 OK

{
  "user_profile": {
    "user": {
      "id": 42,
      "phone_number": "+254712345678",
      "first_name": "Jane",
      "last_name": "Doe",
      "username": "jane",
      "email": "jane@acme.co",
      "is_admin": false,
      "status": "active"
    },
    "accounts": [
      {
        "id": 63,
        "name": "Vendor A",
        "uuid": "acc_2b9c…",
        "status": "active",
        "email": "vendor-a@acme.co",
        "currency": "KES",
        "phone_number": "+254711000111",
        "organization": {
          "id": 9,
          "name": "Acme Group",
          "organization_type": "business",
          "kyc_tier": 3,
          "status": "active",
          "admin_id": 42,
          "creator_id": 42
        },
        "kyc_tier": 3,
        "is_approved": true,
        "merchant_id": 0
      }
    ],
    "roles": { "63": "owner" },
    "status": "active",
    "is_pin_set": true,
    "is_kyc_verified": true,
    "kyc_tier": 3,
    "organizations": [
      { "id": 9, "name": "Acme Group", "organization_type": "business", "status": "active", "currency": "KES" }
    ]
  }
}

Create a Team

Provision a new Account under your organization. A dedicated service wallet is created automatically for the Team as part of this call.

cURL

curl -X POST "$PH_BASE_URL/api/v2/accounts" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 9,
    "name": "Vendor A",
    "description": "WiFi vendor onboarded via our platform",
    "email": "vendor-a@acme.co",
    "dial_code": "+254",
    "number": "711000111"
  }'

Python

import requests

resp = requests.post(
    f"{base_url}/api/v2/accounts",
    auth=(username, password),
    json={
        "organization_id": 9,
        "name": "Vendor A",
        "description": "WiFi vendor onboarded via our platform",
        "email": "vendor-a@acme.co",
        "dial_code": "+254",
        "number": "711000111",
    },
)
print(resp.json())

TypeScript

const resp = await fetch(`${baseUrl}/api/v2/accounts`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa(`${username}:${password}`),
  },
  body: JSON.stringify({
    organization_id: 9,
    name: "Vendor A",
    description: "WiFi vendor onboarded via our platform",
    email: "vendor-a@acme.co",
    dial_code: "+254",
    number: "711000111",
  }),
});
console.log(await resp.json());

POST /api/v2/accounts

Field	Type	Required	Notes
organization_id	integer	Yes	The organization the Team belongs to.
name	string	Yes	Display name of the Team.
description	string	No	Free-text description.
email	string	No	Contact email for the Team.
dial_code	string	No*	E.164 country dial code, e.g. +254. Combined with number.
number	string	No*	Local phone number. The Team’s currency is derived from this number’s country.
user_id	integer	No	Creator. Defaults to the user behind the API key.
username	string	No	Custom account UUID/slug. Auto-generated when omitted.

* Provide dial_code + number together — they set the Team’s phone and determine its currency.

200 OK

{
  "account": {
    "id": 63,
    "organization_id": 9,
    "name": "Vendor A",
    "description": "WiFi vendor onboarded via our platform",
    "currency": "KES",
    "number": "254711000111",
    "email": "vendor-a@acme.co",
    "status": "active",
    "account_type": "prepaid",
    "kyc_tier": 1,
    "kyc_verified": false,
    "service_wallet_balance": 0,
    "created_at": "2026-07-06T09:12:44Z",
    "updated_at": "2026-07-06T09:12:44Z"
  }
}

A wallet comes for free

Creating a Team enqueues a scoped service wallet for it. Collections into that Team land in its own wallet — balances never mix across Teams.

Fetch a Team

curl "$PH_BASE_URL/api/v2/account/63" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD"

GET /api/v2/account/{account_id} → returns the same { "account": { … } } shape as Create.

Update a Team

Update settings on an existing Team. Identify the Team with account_id.

curl -X PUT "$PH_BASE_URL/api/v2/accounts" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 63,
    "description": "Renamed vendor",
    "email": "billing@vendor-a.co",
    "logo": "https://cdn.acme.co/vendor-a.png",
    "theme_color": "#0A7C4A",
    "notify_amount": 500
  }'

PUT /api/v2/accounts

Field	Type	Notes
account_id	integer	Required — the Team to update.
description	string	Team description.
email	string	Contact email.
logo	string	Logo URL.
theme_color	string	Brand color (hex).
notify_amount	number	Low-balance notification threshold.
payment_note	string	Note shown on payment pages.

Returns the updated { "account": { … } }.

Delete a Team

curl -X DELETE "$PH_BASE_URL/api/v2/accounts/63" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD"

DELETE /api/v2/accounts/{account_id} — returns the deleted { "account": { … } }.

Caution

Deleting a Team is destructive. Settle and reconcile the Team’s wallet before removing it.