Billing & subscribers

Paths below are relative to the base URL. Every operation also answers 401, 429 and 500 as listed, and carries rate-limit headers. Writes that create a record or move money need an Idempotency-Key. Examples use made-up data for the ISP Amani Link.

Account

Who the API key is and which ISP it acts on.

Get the API key and the ISP it acts on#

GET/account

Returns the calling key (name, scopes, rate limit, expiry) and the ISP it acts on. Use it first to check a key works and to learn the ISP's currency and time zone. Changes nothing.

ScopereadRead-only

Responses

200Success. Returns Account.

Response fields · Account · 2

Name	Type	Description
`key`	ApiKeyInfo
`tenant`	Tenant

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopetenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/account" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "key": {
    "name": "amani-crm",
    "prefix": "cs_live_xxxx",
    "kind": "TENANT",
    "scopes": [
      "read",
      "write"
    ],
    "rate_limit_per_minute": 120,
    "expires_at": null
  },
  "tenant": {
    "code": "AMANI",
    "name": "Amani Link",
    "status": "ACTIVE",
    "currency": "KES",
    "country_code": "KE",
    "timezone": "Africa/Nairobi"
  }
}

Subscribers

An ISP's customers: who they are, plan, balance, invoices, payments, connection; suspend, reactivate, change plan.

List subscribers#

GET/subscribers

Lists the ISP's subscribers, newest first, optionally filtered by status or a free-text search over name, username, account number, paybill code, email and phone. To find one person by an exact phone, email or account number, use lookupSubscribers instead. Changes nothing.

ScopereadCreator needsBILLING:SUBSCRIBERS:VIEWRead-only

Parameters

Name	Type	Description
`status`query	string	Only subscribers in this state. ONLINE / OFFLINE filter on the live connection. One of: `ACTIVESUSPENDEDPENDINGDRAFTTERMINATEDONLINEOFFLINE`
`q`query	string	Free-text search (partial matches). Example: `kamau`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of SubscriberSummary.

Fields of each item · SubscriberSummary · 13

Name	Type	Description
`id`	string	Subscriber id. Use it in every /subscribers/{id} operation. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number. Example: `AL-01042`
`subscriber_code`	string	The billing code the customer types as the M-Pesa paybill account reference. Example: `AL1042`
`username`	string	PPPoE / RADIUS login name. Example: `wanjiku.k`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`
`email`	string	Email address, if the ISP has one. Example: `wanjiku@example.com`
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`service_type`	string	How the subscriber connects. One of: `PPPOEHOTSPOTSTATICBOTH`
`online`	boolean	True while the subscriber has a live session. Example: `true`
`plan_name`	string	Name of the plan on the current subscription, if any. Example: `Home 10 Mbps`
`expires_at`	string · date-time	When the current subscription runs out (UTC). Example: `2026-11-25T09:00:00Z`
`credit_balance`	Money

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers?status=SUSPENDED&size=50" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
      "account_number": "AL-01042",
      "subscriber_code": "AL1042",
      "username": "wanjiku.k",
      "name": "Wanjiku Kamau",
      "phone": "+254712345678",
      "email": "wanjiku@example.com",
      "status": "ACTIVE",
      "service_type": "PPPOE",
      "online": true,
      "plan_name": "Home 10 Mbps",
      "expires_at": "2026-11-25T09:00:00Z",
      "credit_balance": {
        "amount": "300.00",
        "currency": "KES"
      }
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Get a subscriber#

GET/subscribers/{id}

Returns one subscriber with their status, current plan and subscription (expiry), balance and whether they are online. Changes nothing.

ScopereadCreator needsBILLING:SUBSCRIBERS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Responses

200Success. Returns Subscriber.

Response fields · Subscriber · 22

Name	Type	Description
`id`	string	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number. Example: `AL-01042`
`subscriber_code`	string	The billing code the customer types as the M-Pesa paybill account reference. Example: `AL1042`
`username`	string	PPPoE / RADIUS login name. Example: `wanjiku.k`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`first_name`	string	First name. Example: `Wanjiku`
`last_name`	string	Last name. Example: `Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`
`phones`	array of string	Every phone number on the account, in E.164 (some accounts carry two).
`email`	string	Email address, if the ISP has one. Example: `wanjiku@example.com`
`type`	string	Account type. One of: `RESIDENTIALBUSINESSCORPORATE`
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`service_type`	string	How the subscriber connects. One of: `PPPOEHOTSPOTSTATICBOTH`
`address`	string	Installation or physical address. Example: `Kilimani, Nairobi`
`zone`	string	Service zone or area name. Example: `Kilimani`
`online`	boolean	True while the subscriber has a live session. Example: `true`
`last_online_at`	string · date-time	When the subscriber was last seen online (UTC). Example: `2026-10-25T08:55:00Z`
`subscription`	Subscription
`balance`	Balance
`created_at`	string · date-time	When the account was created (UTC). Example: `2025-03-02T10:15:00Z`
`activated_at`	string · date-time	When service was last activated (UTC). Example: `2025-03-02T12:00:00Z`
`suspended_at`	string · date-time	When service was last suspended (UTC), if it is suspended.

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
  "account_number": "AL-01042",
  "subscriber_code": "AL1042",
  "username": "wanjiku.k",
  "name": "Wanjiku Kamau",
  "first_name": "Wanjiku",
  "last_name": "Kamau",
  "phone": "+254712345678",
  "phones": [
    "+254712345678"
  ],
  "email": "wanjiku@example.com",
  "type": "RESIDENTIAL",
  "status": "ACTIVE",
  "service_type": "PPPOE",
  "address": "Kilimani, Nairobi",
  "zone": "Kilimani",
  "online": true,
  "last_online_at": "2026-10-25T08:55:00Z",
  "subscription": {
    "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "status": "ACTIVE",
    "plan": {
      "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "code": "HOME10",
      "name": "Home 10 Mbps",
      "price": {
        "amount": "1500.00",
        "currency": "KES"
      }
    },
    "starts_at": "2026-10-25T09:00:00Z",
    "expires_at": "2026-11-25T09:00:00Z",
    "auto_renew": true,
    "price": {
      "amount": "1500.00",
      "currency": "KES"
    },
    "pending_plan_id": null
  },
  "balance": {
    "credit": {
      "amount": "300.00",
      "currency": "KES"
    },
    "outstanding": {
      "amount": "0.00",
      "currency": "KES"
    },
    "open_invoices": 1,
    "next_renewal_amount": {
      "amount": "1500.00",
      "currency": "KES"
    },
    "expires_at": "2026-11-25T09:00:00Z"
  },
  "created_at": "2025-03-02T10:15:00Z",
  "activated_at": "2025-03-02T12:00:00Z",
  "suspended_at": null
}

Find subscribers by phone, email or account number#

GET/subscribers/lookup

Finds subscribers by exactly one identifier. phone accepts any format (0712345678, 254712345678, +254 712 345 678) and matches however the number is stored; email ignores case; account matches the account number, the paybill code or the PPPoE username exactly. Usually returns one subscriber, but one phone can belong to several accounts. Use it to match a caller or a customer from another system. Changes nothing.

ScopereadCreator needsBILLING:SUBSCRIBERS:VIEWRead-only

Parameters

Name	Type	Description
`phone`query	string	Phone number in any common format; compared as E.164. Example: `+254712345678`
`email`query	string	Email address (case-insensitive, exact). Example: `wanjiku@example.com`
`account`query	string	Account number, paybill code or PPPoE username (exact). Example: `AL-01042`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of SubscriberSummary.

Fields of each item · SubscriberSummary · 13

Name	Type	Description
`id`	string	Subscriber id. Use it in every /subscribers/{id} operation. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number. Example: `AL-01042`
`subscriber_code`	string	The billing code the customer types as the M-Pesa paybill account reference. Example: `AL1042`
`username`	string	PPPoE / RADIUS login name. Example: `wanjiku.k`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`
`email`	string	Email address, if the ISP has one. Example: `wanjiku@example.com`
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`service_type`	string	How the subscriber connects. One of: `PPPOEHOTSPOTSTATICBOTH`
`online`	boolean	True while the subscriber has a live session. Example: `true`
`plan_name`	string	Name of the plan on the current subscription, if any. Example: `Home 10 Mbps`
`expires_at`	string · date-time	When the current subscription runs out (UTC). Example: `2026-11-25T09:00:00Z`
`credit_balance`	Money

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/lookup?phone=%2B254712345678" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
      "account_number": "AL-01042",
      "subscriber_code": "AL1042",
      "username": "wanjiku.k",
      "name": "Wanjiku Kamau",
      "phone": "+254712345678",
      "email": "wanjiku@example.com",
      "status": "ACTIVE",
      "service_type": "PPPOE",
      "online": true,
      "plan_name": "Home 10 Mbps",
      "expires_at": "2026-11-25T09:00:00Z",
      "credit_balance": {
        "amount": "300.00",
        "currency": "KES"
      }
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Get what a subscriber has paid ahead and owes#

GET/subscribers/{id}/balance

Returns the subscriber's wallet credit, the total of their unpaid invoices, what the next cycle costs and when the current one ends. Use it to answer "how much do I owe" or "when does my internet expire". Changes nothing.

ScopereadCreator needsBILLING:SUBSCRIBERS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Responses

200Success. Returns Balance.

Response fields · Balance · 5

Name	Type	Description
`credit`	Money
`outstanding`	Money
`open_invoices`	integer · int32	How many invoices are unpaid. Example: `1`
`next_renewal_amount`	Money
`expires_at`	string · date-time	When the current subscription runs out (UTC). Example: `2026-11-25T09:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/balance" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "credit": {
    "amount": "300.00",
    "currency": "KES"
  },
  "outstanding": {
    "amount": "0.00",
    "currency": "KES"
  },
  "open_invoices": 1,
  "next_renewal_amount": {
    "amount": "1500.00",
    "currency": "KES"
  },
  "expires_at": "2026-11-25T09:00:00Z"
}

Get a subscriber's connection#

GET/subscribers/{id}/session

Says whether the subscriber is online now, with the live RADIUS session (IP, router, since when, data used) and their last ended session (when and why it dropped). Use it for "is my internet on" or "when did it drop". Changes nothing.

ScopereadCreator needsSYSTEM:DASHBOARD:VIEW or BILLING:SUBSCRIBERS:READRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Responses

200Success. Returns SubscriberSession.

Response fields · SubscriberSession · 3

Name Type Description

Name	Type	Description
`online`	boolean	True when the subscriber has a live session. Example: `true`
`current`	Session
`last_session`	Session

online

boolean

True when the subscriber has a live session.

Example: true

current Session

last_session Session

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/session" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "online": true,
  "current": {
    "id": "4815162342",
    "type": "PPPOE",
    "username": "wanjiku.k",
    "subscriber": {
      "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
      "account_number": "AL-01042",
      "name": "Wanjiku Kamau",
      "phone": "+254712345678"
    },
    "ip_address": "10.6.0.25",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "nas_ip": "10.10.0.1",
    "nas_name": "Kilimani-CCR",
    "started_at": "2026-10-25T06:12:00Z",
    "ended_at": null,
    "end_cause": null,
    "duration_seconds": 9840,
    "bytes_up": 104857600,
    "bytes_down": 2147483648
  },
  "last_session": {
    "id": "4815162342",
    "type": "PPPOE",
    "username": "wanjiku.k",
    "subscriber": {
      "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
      "account_number": "AL-01042",
      "name": "Wanjiku Kamau",
      "phone": "+254712345678"
    },
    "ip_address": "10.6.0.25",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "nas_ip": "10.10.0.1",
    "nas_name": "Kilimani-CCR",
    "started_at": "2026-10-25T06:12:00Z",
    "ended_at": null,
    "end_cause": null,
    "duration_seconds": 9840,
    "bytes_up": 104857600,
    "bytes_down": 2147483648
  }
}

List a subscriber's invoices#

GET/subscribers/{id}/invoices

Lists the invoices issued to one subscriber, newest first. Changes nothing.

ScopereadCreator needsBILLING:SUBSCRIBERS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

pagequery

integer · int32

Page number, starting at 1.

Limits: at least 1. Default 1.

Example: 1

sizequery

integer · int32

Results per page, 1–200.

Limits: 1–200. Default 50.

Example: 50

Responses

200Success. A page of Invoice.

Fields of each item · Invoice · 12

Name	Type	Description
`id`	string	Invoice id. Example: `7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d`
`number`	string	Invoice number as printed. Example: `INV-202610-0042`
`subscriber`	SubscriberRef
`plan_name`	string	The plan billed, as it was named when the invoice was issued. Example: `Home 10 Mbps`
`amount`	Money
`status`	string	ISSUED: unpaid. OVERDUE: unpaid past the due date. PAID. VOID: cancelled. One of: `ISSUEDPAIDOVERDUEVOID`
`issued_on`	string · date	Issue date (ISO 8601 date). Example: `2026-10-01`
`due_on`	string · date	Due date (ISO 8601 date). Example: `2026-10-08`
`paid_on`	string · date	Date it was paid, if it was.
`payment_id`	string	The payment that settled it, if any.
`payment_reference`	string	Receipt / reference of the settling payment. Example: `SAMPLE7Q2Z`
`created_at`	string · date-time	When the invoice record was created (UTC). Example: `2026-10-01T05:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/invoices" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "number": "INV-202610-0042",
      "subscriber": {
        "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
        "account_number": "AL-01042",
        "name": "Wanjiku Kamau",
        "phone": "+254712345678"
      },
      "plan_name": "Home 10 Mbps",
      "amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "status": "ISSUED",
      "issued_on": "2026-10-01",
      "due_on": "2026-10-08",
      "paid_on": null,
      "payment_id": null,
      "payment_reference": "SAMPLE7Q2Z",
      "created_at": "2026-10-01T05:00:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

List a subscriber's payments#

GET/subscribers/{id}/payments

Lists the payments applied to one subscriber, newest first. Changes nothing.

ScopereadCreator needsBILLING:PAYMENTS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

pagequery

integer · int32

Page number, starting at 1.

Limits: at least 1. Default 1.

Example: 1

sizequery

integer · int32

Results per page, 1–200.

Limits: 1–200. Default 50.

Example: 50

Responses

200Success. A page of Payment.

Fields of each item · Payment · 13

Name	Type	Description
`id`	string	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`
`subscriber`	SubscriberRef
`amount`	Money
`provider`	string	Where the money came from, e.g. MPESA, KCB, EQUITY, CASH, BANK. Example: `MPESA`
`method`	string	How it arrived: STK_PUSH, PAYBILL, TILL, MANUAL (recorded by staff or the API). Example: `PAYBILL`
`reference`	string	The provider's receipt / transaction reference. Unique per provider. Example: `SAMPLE7Q2Z`
`payer_phone`	string	The payer's phone in E.164, when the provider gives it. Example: `+254712345678`
`account_reference`	string	What the payer typed as the account / reference. Example: `AL1042`
`status`	string	PENDING, COMPLETED, FAILED or REVERSED. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`applied`	boolean	True once the money has been credited to the subscriber's wallet / renewal. Example: `true`
`applied_at`	string · date-time	When it was applied (UTC). Example: `2026-10-25T09:00:05Z`
`not_applied_amount`	Money
`received_at`	string · date-time	When the payment was received (UTC). Example: `2026-10-25T09:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/payments" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "subscriber": {
        "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
        "account_number": "AL-01042",
        "name": "Wanjiku Kamau",
        "phone": "+254712345678"
      },
      "amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "provider": "MPESA",
      "method": "PAYBILL",
      "reference": "SAMPLE7Q2Z",
      "payer_phone": "+254712345678",
      "account_reference": "AL1042",
      "status": "COMPLETED",
      "applied": true,
      "applied_at": "2026-10-25T09:00:05Z",
      "not_applied_amount": {
        "amount": "0.00",
        "currency": "KES"
      },
      "received_at": "2026-10-25T09:00:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Change a subscriber's plan#

POST/subscribers/{id}/plan

Moves the subscriber to another plan now, without a payment: their speed and price change immediately and the subscription end date stays where it is. The reason is recorded for the ISP's reports. Use listPlans to find plan ids. For a paid upgrade, record the payment as well.

Scopesubscribers:writeCreator needsBILLING:SUBSCRIPTIONS:CREATEChanges data

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Request body

Move a subscriber to another plan now, without a payment and without moving their expiry date.

Name Type Description

Name	Type	Description
`plan_id`required	string	The new plan (an ACTIVE plan from `listPlans`). Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`
`reason`required	string	Why the plan is changing; reported in the ISP's plan-change reports. One of: `CUSTOMER_REQUESTAFFORDABILITYPROMOTIONRETENTION_OFFERSERVICE_QUALITYBILLING_CORRECTIONMIGRATIONOTHER`
`notes`	string	Notes. Required when reason is OTHER. Limits: up to 300 characters. Example: `Moving to the business plan after opening a shop`

plan_idrequired

string

The new plan (an ACTIVE plan from listPlans).

Example: 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f

reasonrequired

string

Why the plan is changing; reported in the ISP's plan-change reports.

One of: CUSTOMER_REQUESTAFFORDABILITYPROMOTIONRETENTION_OFFERSERVICE_QUALITYBILLING_CORRECTIONMIGRATIONOTHER

notes

string

Notes. Required when reason is OTHER.

Limits: up to 300 characters.

Example: Moving to the business plan after opening a shop

Responses

200Plan changed. Returns SubscriberChange.

Response fields · SubscriberChange · 3

Name Type Description

Name	Type	Description
`outcome`	string	done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin. One of: `doneapproval_pending`
`subscriber`	Subscriber
`approval_request_id`	string	The approval request filed, when outcome is approval_pending.

outcome

string

done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin.

One of: doneapproval_pending

subscriber Subscriber

approval_request_id

string

The approval request filed, when outcome is approval_pending.

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
422plan_inactiveno_subscriptionsame_planplan_change_failed
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/plan" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "reason": "CUSTOMER_REQUEST",
    "notes": "Moving to the business plan after opening a shop"
  }'

Response · 200

{
  "outcome": "done",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "subscriber_code": "AL1042",
    "username": "wanjiku.k",
    "name": "Wanjiku Kamau",
    "first_name": "Wanjiku",
    "last_name": "Kamau",
    "phone": "+254712345678",
    "phones": [
      "+254712345678"
    ],
    "email": "wanjiku@example.com",
    "type": "RESIDENTIAL",
    "status": "ACTIVE",
    "service_type": "PPPOE",
    "address": "Kilimani, Nairobi",
    "zone": "Kilimani",
    "online": true,
    "last_online_at": "2026-10-25T08:55:00Z",
    "subscription": {
      "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
      "status": "ACTIVE",
      "plan": {
        "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "code": "HOME10",
        "name": "Home 10 Mbps",
        "price": {
          "amount": "1500.00",
          "currency": "KES"
        }
      },
      "starts_at": "2026-10-25T09:00:00Z",
      "expires_at": "2026-11-25T09:00:00Z",
      "auto_renew": true,
      "price": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "pending_plan_id": null
    },
    "balance": {
      "credit": {
        "amount": "300.00",
        "currency": "KES"
      },
      "outstanding": {
        "amount": "0.00",
        "currency": "KES"
      },
      "open_invoices": 1,
      "next_renewal_amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "expires_at": "2026-11-25T09:00:00Z"
    },
    "created_at": "2025-03-02T10:15:00Z",
    "activated_at": "2025-03-02T12:00:00Z",
    "suspended_at": null
  },
  "approval_request_id": null
}

Suspend a subscriber's service#

POST/subscribers/{id}/suspend

Turns the subscriber's internet off now: their status becomes SUSPENDED, RADIUS throttles them (or the router queue is closed for a static line) and any live session is disconnected. Billing records are kept and the subscription end date does not move. If the ISP requires a manager's approval for suspensions, nothing changes yet: an approval request is filed and the answer is 202 with outcome approval_pending. Suspending an already suspended subscriber changes nothing and answers done.

Scopesubscribers:writeCreator needsBILLING:SUBSCRIBERS:EDITChanges data

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Request body

Why the subscriber is being suspended. Recorded on their timeline.

Name Type Description

Name	Type	Description
`reason`required	string	Reason, shown on the subscriber's timeline and to approvers. Limits: 3–300 characters. Example: `Customer asked to pause service while travelling`

reasonrequired

string

Reason, shown on the subscriber's timeline and to approvers.

Limits: 3–300 characters.

Example: Customer asked to pause service while travelling

Responses

200Suspended (or already suspended). Returns SubscriberChange.
202The ISP requires approval; a request was filed. Returns SubscriberChange.

Response fields · SubscriberChange · 3

Name Type Description

Name	Type	Description
`outcome`	string	done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin. One of: `doneapproval_pending`
`subscriber`	Subscriber
`approval_request_id`	string	The approval request filed, when outcome is approval_pending.

outcome

string

done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin.

One of: doneapproval_pending

subscriber Subscriber

approval_request_id

string

The approval request filed, when outcome is approval_pending.

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
422invalid_statesuspend_failedapproval_unavailable
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/suspend" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer asked to pause service while travelling"
  }'

Response · 200

{
  "outcome": "done",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "subscriber_code": "AL1042",
    "username": "wanjiku.k",
    "name": "Wanjiku Kamau",
    "first_name": "Wanjiku",
    "last_name": "Kamau",
    "phone": "+254712345678",
    "phones": [
      "+254712345678"
    ],
    "email": "wanjiku@example.com",
    "type": "RESIDENTIAL",
    "status": "SUSPENDED",
    "service_type": "PPPOE",
    "address": "Kilimani, Nairobi",
    "zone": "Kilimani",
    "online": false,
    "last_online_at": "2026-10-25T08:55:00Z",
    "subscription": {
      "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
      "status": "SUSPENDED",
      "plan": {
        "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "code": "HOME10",
        "name": "Home 10 Mbps",
        "price": {
          "amount": "1500.00",
          "currency": "KES"
        }
      },
      "starts_at": "2026-10-25T09:00:00Z",
      "expires_at": "2026-11-25T09:00:00Z",
      "auto_renew": true,
      "price": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "pending_plan_id": null
    },
    "balance": {
      "credit": {
        "amount": "300.00",
        "currency": "KES"
      },
      "outstanding": {
        "amount": "0.00",
        "currency": "KES"
      },
      "open_invoices": 1,
      "next_renewal_amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "expires_at": "2026-11-25T09:00:00Z"
    },
    "created_at": "2025-03-02T10:15:00Z",
    "activated_at": "2025-03-02T12:00:00Z",
    "suspended_at": "2026-11-04T07:30:00Z"
  },
  "approval_request_id": null
}

Reactivate a suspended subscriber without a payment#

POST/subscribers/{id}/reactivate

Turns a SUSPENDED subscriber's internet back on without taking money, with a reason recorded on their timeline. If their subscription had already expired it is extended by one plan cycle from now, free of charge, exactly as the portal does. When the customer has paid, use recordPayment instead: it renews and reactivates them properly. Reactivating an ACTIVE subscriber changes nothing and answers done.

Scopesubscribers:writeCreator needsBILLING:SUBSCRIBERS:EDITChanges data

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Subscriber id.

Example: 3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f

Request body

Why the subscriber is being reactivated without a payment. To reactivate by payment, use recordPayment instead.

Name Type Description

Name	Type	Description
`reason`required	string	Reason, shown on the subscriber's timeline. Limits: 3–300 characters. Example: `Paid in cash at the office; receipt to follow`

reasonrequired

string

Reason, shown on the subscriber's timeline.

Limits: 3–300 characters.

Example: Paid in cash at the office; receipt to follow

Responses

200Reactivated (or already active). Returns SubscriberChange.

Response fields · SubscriberChange · 3

Name Type Description

Name	Type	Description
`outcome`	string	done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin. One of: `doneapproval_pending`
`subscriber`	Subscriber
`approval_request_id`	string	The approval request filed, when outcome is approval_pending.

outcome

string

done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin.

One of: doneapproval_pending

subscriber Subscriber

approval_request_id

string

The approval request filed, when outcome is approval_pending.

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
422invalid_stateno_active_subscriptionreactivate_failed
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/reactivate" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Paid in cash at the office; receipt to follow"
  }'

Response · 200

{
  "outcome": "done",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "subscriber_code": "AL1042",
    "username": "wanjiku.k",
    "name": "Wanjiku Kamau",
    "first_name": "Wanjiku",
    "last_name": "Kamau",
    "phone": "+254712345678",
    "phones": [
      "+254712345678"
    ],
    "email": "wanjiku@example.com",
    "type": "RESIDENTIAL",
    "status": "ACTIVE",
    "service_type": "PPPOE",
    "address": "Kilimani, Nairobi",
    "zone": "Kilimani",
    "online": true,
    "last_online_at": "2026-10-25T08:55:00Z",
    "subscription": {
      "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
      "status": "ACTIVE",
      "plan": {
        "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "code": "HOME10",
        "name": "Home 10 Mbps",
        "price": {
          "amount": "1500.00",
          "currency": "KES"
        }
      },
      "starts_at": "2026-10-25T09:00:00Z",
      "expires_at": "2026-11-25T09:00:00Z",
      "auto_renew": true,
      "price": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "pending_plan_id": null
    },
    "balance": {
      "credit": {
        "amount": "300.00",
        "currency": "KES"
      },
      "outstanding": {
        "amount": "0.00",
        "currency": "KES"
      },
      "open_invoices": 1,
      "next_renewal_amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "expires_at": "2026-11-25T09:00:00Z"
    },
    "created_at": "2025-03-02T10:15:00Z",
    "activated_at": "2025-03-02T12:00:00Z",
    "suspended_at": null
  },
  "approval_request_id": null
}

Sessions

Who is online right now.

List who is online now#

GET/sessions

Lists live RADIUS sessions on the ISP's routers, newest first: PPPoE subscribers and hotspot devices, with IP, MAC, router, start time and data used. total is the number online. For one subscriber use getSubscriberSession. Changes nothing.

ScopereadCreator needsSYSTEM:DASHBOARD:VIEW or BILLING:SUBSCRIBERS:READRead-only

Parameters

Name	Type	Description
`type`query	string	Only PPPoE subscribers or only hotspot devices. One of: `PPPOEHOTSPOT`
`q`query	string	Search over username, MAC and IP (partial). Example: `wanjiku`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of Session.

Fields of each item · Session · 14

Name	Type	Description
`id`	string	Session id (RADIUS accounting row id). Example: `4815162342`
`type`	string	PPPOE or HOTSPOT. One of: `PPPOEHOTSPOT`
`username`	string	RADIUS username (PPPoE login, or the voucher / MAC for hotspot). Example: `wanjiku.k`
`subscriber`	SubscriberRef
`ip_address`	string	IP address assigned to the connection. Example: `10.6.0.25`
`mac_address`	string	The device's MAC address, as the router reports it. Example: `AA:BB:CC:DD:EE:FF`
`nas_ip`	string	The router (NAS) the session is on. Example: `10.10.0.1`
`nas_name`	string	The router's name. Example: `Kilimani-CCR`
`started_at`	string · date-time	When the session started (UTC). Example: `2026-10-25T06:12:00Z`
`ended_at`	string · date-time	When it ended (UTC); null while it is live.
`end_cause`	string	Why it ended, as RADIUS reports it (e.g. Lost-Carrier, User-Request, Admin-Reset); null while live.
`duration_seconds`	integer · int64	Length of the session so far, in seconds. Example: `9840`
`bytes_up`	integer · int64	Bytes the subscriber uploaded in this session. Example: `104857600`
`bytes_down`	integer · int64	Bytes the subscriber downloaded in this session. Example: `2147483648`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/sessions" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "4815162342",
      "type": "PPPOE",
      "username": "wanjiku.k",
      "subscriber": {
        "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
        "account_number": "AL-01042",
        "name": "Wanjiku Kamau",
        "phone": "+254712345678"
      },
      "ip_address": "10.6.0.25",
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "nas_ip": "10.10.0.1",
      "nas_name": "Kilimani-CCR",
      "started_at": "2026-10-25T06:12:00Z",
      "ended_at": null,
      "end_cause": null,
      "duration_seconds": 9840,
      "bytes_up": 104857600,
      "bytes_down": 2147483648
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Plans

The service plans an ISP sells.

List plans#

GET/plans

Lists the ISP's service plans with price, cycle length and speed, sorted by name. Use it to answer "what packages do you have" or to find the plan_id for changeSubscriberPlan. Changes nothing.

ScopereadCreator needsBILLING:PLANS:VIEWRead-only

Parameters

Name	Type	Description
`status`query	string	Only plans with this status. One of: `ACTIVEINACTIVEARCHIVED`
`type`query	string	FIXED (home/business lines) or HOTSPOT (WiFi vouchers). One of: `FIXEDHOTSPOT`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of Plan.

Fields of each item · Plan · 15

Name	Type	Description
`id`	string	Plan id. Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`
`code`	string	Plan code. Example: `HOME10`
`name`	string	Plan name as customers see it. Example: `Home 10 Mbps`
`description`	string	Free-text description. Example: `Unlimited home fibre, 10 Mbps`
`type`	string	FIXED: a home/business line (PPPoE or static). HOTSPOT: a WiFi voucher package. One of: `FIXEDHOTSPOT`
`price`	Money
`validity_value`	integer · int32	Length of one cycle, in validity_unit. Example: `30`
`validity_unit`	string	Unit of the cycle length. One of: `MINUTESHOURSDAYSWEEKSMONTHSYEARS`
`download_mbps`	number · double	Download speed in Mbps, when the plan has a speed profile. Example: `10`
`upload_mbps`	number · double	Upload speed in Mbps, when the plan has a speed profile. Example: `5`
`data_limit_bytes`	integer · int64	Data cap per cycle in bytes; null means unlimited.
`max_devices`	integer · int32	How many devices may be online at once; null uses the ISP default. Example: `1`
`status`	string	Plan status. Only ACTIVE plans can be assigned. One of: `ACTIVEINACTIVEARCHIVED`
`visible`	boolean	Whether customers see the plan on self-service pages. Example: `true`
`created_at`	string · date-time	When the plan was created (UTC). Example: `2026-01-10T07:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/plans" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "code": "HOME10",
      "name": "Home 10 Mbps",
      "description": "Unlimited home fibre, 10 Mbps",
      "type": "FIXED",
      "price": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "validity_value": 30,
      "validity_unit": "DAYS",
      "download_mbps": 10,
      "upload_mbps": 5,
      "data_limit_bytes": null,
      "max_devices": 1,
      "status": "ACTIVE",
      "visible": true,
      "created_at": "2026-01-10T07:00:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Get a plan#

GET/plans/{id}

Returns one service plan. Changes nothing.

ScopereadCreator needsBILLING:PLANS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Plan id. Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`

idrequiredpath

string · uuid

Plan id.

Example: 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f

Responses

200Success. Returns Plan.

Response fields · Plan · 15

Name	Type	Description
`id`	string	Plan id. Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`
`code`	string	Plan code. Example: `HOME10`
`name`	string	Plan name as customers see it. Example: `Home 10 Mbps`
`description`	string	Free-text description. Example: `Unlimited home fibre, 10 Mbps`
`type`	string	FIXED: a home/business line (PPPoE or static). HOTSPOT: a WiFi voucher package. One of: `FIXEDHOTSPOT`
`price`	Money
`validity_value`	integer · int32	Length of one cycle, in validity_unit. Example: `30`
`validity_unit`	string	Unit of the cycle length. One of: `MINUTESHOURSDAYSWEEKSMONTHSYEARS`
`download_mbps`	number · double	Download speed in Mbps, when the plan has a speed profile. Example: `10`
`upload_mbps`	number · double	Upload speed in Mbps, when the plan has a speed profile. Example: `5`
`data_limit_bytes`	integer · int64	Data cap per cycle in bytes; null means unlimited.
`max_devices`	integer · int32	How many devices may be online at once; null uses the ISP default. Example: `1`
`status`	string	Plan status. Only ACTIVE plans can be assigned. One of: `ACTIVEINACTIVEARCHIVED`
`visible`	boolean	Whether customers see the plan on self-service pages. Example: `true`
`created_at`	string · date-time	When the plan was created (UTC). Example: `2026-01-10T07:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/plans/9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "code": "HOME10",
  "name": "Home 10 Mbps",
  "description": "Unlimited home fibre, 10 Mbps",
  "type": "FIXED",
  "price": {
    "amount": "1500.00",
    "currency": "KES"
  },
  "validity_value": 30,
  "validity_unit": "DAYS",
  "download_mbps": 10,
  "upload_mbps": 5,
  "data_limit_bytes": null,
  "max_devices": 1,
  "status": "ACTIVE",
  "visible": true,
  "created_at": "2026-01-10T07:00:00Z"
}

Invoices

Invoices issued to subscribers.

List invoices#

GET/invoices

Lists the ISP's invoices, newest first, filtered by status, issue date or a search over the subscriber's name, phone, username and the invoice number. For one subscriber's invoices use listSubscriberInvoices. Changes nothing.

ScopereadCreator needsSYSTEM:DASHBOARD:VIEWRead-only

Parameters

Name	Type	Description
`status`query	string	Only invoices in this state. One of: `ISSUEDPAIDOVERDUEVOID`
`from`query	string · date	Issued on or after this date (YYYY-MM-DD). Example: `2026-10-01`
`to`query	string · date	Issued on or before this date (YYYY-MM-DD). Example: `2026-10-31`
`q`query	string	Free-text search. Example: `INV-202610`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of Invoice.

Fields of each item · Invoice · 12

Name	Type	Description
`id`	string	Invoice id. Example: `7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d`
`number`	string	Invoice number as printed. Example: `INV-202610-0042`
`subscriber`	SubscriberRef
`plan_name`	string	The plan billed, as it was named when the invoice was issued. Example: `Home 10 Mbps`
`amount`	Money
`status`	string	ISSUED: unpaid. OVERDUE: unpaid past the due date. PAID. VOID: cancelled. One of: `ISSUEDPAIDOVERDUEVOID`
`issued_on`	string · date	Issue date (ISO 8601 date). Example: `2026-10-01`
`due_on`	string · date	Due date (ISO 8601 date). Example: `2026-10-08`
`paid_on`	string · date	Date it was paid, if it was.
`payment_id`	string	The payment that settled it, if any.
`payment_reference`	string	Receipt / reference of the settling payment. Example: `SAMPLE7Q2Z`
`created_at`	string · date-time	When the invoice record was created (UTC). Example: `2026-10-01T05:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/invoices" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "number": "INV-202610-0042",
      "subscriber": {
        "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
        "account_number": "AL-01042",
        "name": "Wanjiku Kamau",
        "phone": "+254712345678"
      },
      "plan_name": "Home 10 Mbps",
      "amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "status": "ISSUED",
      "issued_on": "2026-10-01",
      "due_on": "2026-10-08",
      "paid_on": null,
      "payment_id": null,
      "payment_reference": "SAMPLE7Q2Z",
      "created_at": "2026-10-01T05:00:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Get an invoice#

GET/invoices/{id}

Returns one invoice. Changes nothing.

ScopereadCreator needsSYSTEM:DASHBOARD:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Invoice id. Example: `7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d`

idrequiredpath

string · uuid

Invoice id.

Example: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d

Responses

200Success. Returns Invoice.

Response fields · Invoice · 12

Name	Type	Description
`id`	string	Invoice id. Example: `7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d`
`number`	string	Invoice number as printed. Example: `INV-202610-0042`
`subscriber`	SubscriberRef
`plan_name`	string	The plan billed, as it was named when the invoice was issued. Example: `Home 10 Mbps`
`amount`	Money
`status`	string	ISSUED: unpaid. OVERDUE: unpaid past the due date. PAID. VOID: cancelled. One of: `ISSUEDPAIDOVERDUEVOID`
`issued_on`	string · date	Issue date (ISO 8601 date). Example: `2026-10-01`
`due_on`	string · date	Due date (ISO 8601 date). Example: `2026-10-08`
`paid_on`	string · date	Date it was paid, if it was.
`payment_id`	string	The payment that settled it, if any.
`payment_reference`	string	Receipt / reference of the settling payment. Example: `SAMPLE7Q2Z`
`created_at`	string · date-time	When the invoice record was created (UTC). Example: `2026-10-01T05:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/invoices/7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "number": "INV-202610-0042",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "name": "Wanjiku Kamau",
    "phone": "+254712345678"
  },
  "plan_name": "Home 10 Mbps",
  "amount": {
    "amount": "1500.00",
    "currency": "KES"
  },
  "status": "ISSUED",
  "issued_on": "2026-10-01",
  "due_on": "2026-10-08",
  "paid_on": null,
  "payment_id": null,
  "payment_reference": "SAMPLE7Q2Z",
  "created_at": "2026-10-01T05:00:00Z"
}

Payments

Money received, and recording a payment.

List payments#

GET/payments

Lists payments received, newest first, by status, provider, whether they matched a subscriber, and time received. matched=false lists money that arrived but could not be tied to a subscriber. Changes nothing.

ScopereadCreator needsBILLING:PAYMENTS:VIEWRead-only

Parameters

Name	Type	Description
`status`query	string	Only payments in this state. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`provider`query	string	Only this provider, e.g. MPESA, KCB, CASH. Example: `MPESA`
`matched`query	boolean	true: only payments tied to a subscriber. false: only unmatched ones. Example: `true`
`from`query	string · date-time	Received at or after this time (ISO 8601, UTC). Example: `2026-10-01T00:00:00Z`
`to`query	string · date-time	Received at or before this time (ISO 8601, UTC). Example: `2026-10-31T23:59:59Z`
`q`query	string	Search over receipt, phone, account reference and subscriber name. Example: `SAMPLE7Q2Z`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

Responses

200Success. A page of Payment.

Fields of each item · Payment · 13

Name	Type	Description
`id`	string	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`
`subscriber`	SubscriberRef
`amount`	Money
`provider`	string	Where the money came from, e.g. MPESA, KCB, EQUITY, CASH, BANK. Example: `MPESA`
`method`	string	How it arrived: STK_PUSH, PAYBILL, TILL, MANUAL (recorded by staff or the API). Example: `PAYBILL`
`reference`	string	The provider's receipt / transaction reference. Unique per provider. Example: `SAMPLE7Q2Z`
`payer_phone`	string	The payer's phone in E.164, when the provider gives it. Example: `+254712345678`
`account_reference`	string	What the payer typed as the account / reference. Example: `AL1042`
`status`	string	PENDING, COMPLETED, FAILED or REVERSED. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`applied`	boolean	True once the money has been credited to the subscriber's wallet / renewal. Example: `true`
`applied_at`	string · date-time	When it was applied (UTC). Example: `2026-10-25T09:00:05Z`
`not_applied_amount`	Money
`received_at`	string · date-time	When the payment was received (UTC). Example: `2026-10-25T09:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/payments?from=2026-10-01T00%3A00%3A00Z&matched=true" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "subscriber": {
        "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
        "account_number": "AL-01042",
        "name": "Wanjiku Kamau",
        "phone": "+254712345678"
      },
      "amount": {
        "amount": "1500.00",
        "currency": "KES"
      },
      "provider": "MPESA",
      "method": "PAYBILL",
      "reference": "SAMPLE7Q2Z",
      "payer_phone": "+254712345678",
      "account_reference": "AL1042",
      "status": "COMPLETED",
      "applied": true,
      "applied_at": "2026-10-25T09:00:05Z",
      "not_applied_amount": {
        "amount": "0.00",
        "currency": "KES"
      },
      "received_at": "2026-10-25T09:00:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Get a payment#

GET/payments/{id}

Returns one payment. Changes nothing.

ScopereadCreator needsBILLING:PAYMENTS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`

idrequiredpath

string · uuid

Payment id.

Example: 1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f

Responses

200Success. Returns Payment.

Response fields · Payment · 13

Name	Type	Description
`id`	string	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`
`subscriber`	SubscriberRef
`amount`	Money
`provider`	string	Where the money came from, e.g. MPESA, KCB, EQUITY, CASH, BANK. Example: `MPESA`
`method`	string	How it arrived: STK_PUSH, PAYBILL, TILL, MANUAL (recorded by staff or the API). Example: `PAYBILL`
`reference`	string	The provider's receipt / transaction reference. Unique per provider. Example: `SAMPLE7Q2Z`
`payer_phone`	string	The payer's phone in E.164, when the provider gives it. Example: `+254712345678`
`account_reference`	string	What the payer typed as the account / reference. Example: `AL1042`
`status`	string	PENDING, COMPLETED, FAILED or REVERSED. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`applied`	boolean	True once the money has been credited to the subscriber's wallet / renewal. Example: `true`
`applied_at`	string · date-time	When it was applied (UTC). Example: `2026-10-25T09:00:05Z`
`not_applied_amount`	Money
`received_at`	string · date-time	When the payment was received (UTC). Example: `2026-10-25T09:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/payments/1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "name": "Wanjiku Kamau",
    "phone": "+254712345678"
  },
  "amount": {
    "amount": "1500.00",
    "currency": "KES"
  },
  "provider": "MPESA",
  "method": "PAYBILL",
  "reference": "SAMPLE7Q2Z",
  "payer_phone": "+254712345678",
  "account_reference": "AL1042",
  "status": "COMPLETED",
  "applied": true,
  "applied_at": "2026-10-25T09:00:05Z",
  "not_applied_amount": {
    "amount": "0.00",
    "currency": "KES"
  },
  "received_at": "2026-10-25T09:00:00Z"
}

Record a payment for a subscriber#

POST/payments

Records money the ISP received outside CoreSync's own channels (cash, a bank transfer, an M-Pesa receipt) and applies it the same way an M-Pesa payment is applied: it goes to the subscriber's wallet, renews their subscription when it covers the plan price (and reactivates a suspended subscriber), and it appears in the ISP's payments and reports. Moves money: needs an Idempotency-Key, and a provider + reference is only ever recorded once, so passing the real receipt makes a duplicate impossible. Answers 201 when recorded, 200 when this exact receipt was already recorded for this subscriber.

Scopepayments:writeCreator needsBILLING:PAYMENTS:EDITChanges dataIdempotency-Key required

Parameters

Name Type Description

Name	Type	Description
`Idempotency-Key`requiredheader	string	A unique string per payment (e.g. a UUID). Retrying with the same key returns the first response instead of recording it again, for 24 hours. Example: `4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11`

Idempotency-Keyrequiredheader

string

A unique string per payment (e.g. a UUID). Retrying with the same key returns the first response instead of recording it again, for 24 hours.

Example: 4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11

Request body

A payment received outside CoreSync's own channels (cash, a bank transfer, an M-Pesa receipt the ISP holds).

Name	Type	Description
`subscriber_id`required	string	The subscriber who paid. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`amount`required	string	Amount received, as a decimal string. Example: `1500.00`
`currency`	string	ISO 4217 currency. Must be the ISP's currency; defaults to it. Limits: 3–3 characters, 3 letters. Example: `KES`
`provider`	string	Where the money came from. Defaults to CASH. One of: `CASHMPESABANKCHEQUECARDOTHER`
`reference`	string	The receipt or transaction reference. A provider + reference pair is only ever recorded once, so pass the real receipt (e.g. the M-Pesa code) to make a duplicate impossible. Generated from the Idempotency-Key when omitted. Limits: up to 100 characters. Example: `SAMPLE7Q2Z`

Responses

201Recorded and applied. Returns Payment.
200This receipt was already recorded for this subscriber; nothing changed. Returns Payment.

Response fields · Payment · 13

Name	Type	Description
`id`	string	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`
`subscriber`	SubscriberRef
`amount`	Money
`provider`	string	Where the money came from, e.g. MPESA, KCB, EQUITY, CASH, BANK. Example: `MPESA`
`method`	string	How it arrived: STK_PUSH, PAYBILL, TILL, MANUAL (recorded by staff or the API). Example: `PAYBILL`
`reference`	string	The provider's receipt / transaction reference. Unique per provider. Example: `SAMPLE7Q2Z`
`payer_phone`	string	The payer's phone in E.164, when the provider gives it. Example: `+254712345678`
`account_reference`	string	What the payer typed as the account / reference. Example: `AL1042`
`status`	string	PENDING, COMPLETED, FAILED or REVERSED. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`applied`	boolean	True once the money has been credited to the subscriber's wallet / renewal. Example: `true`
`applied_at`	string · date-time	When it was applied (UTC). Example: `2026-10-25T09:00:05Z`
`not_applied_amount`	Money
`received_at`	string · date-time	When the payment was received (UTC). Example: `2026-10-25T09:00:00Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameteridempotency_key_required
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
409idempotency_in_progressduplicate_reference
422idempotency_key_reusedcurrency_mismatchpayment_not_applied
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/payments" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11" \
  -d '{
    "subscriber_id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "amount": "1500.00",
    "currency": "KES",
    "provider": "MPESA",
    "reference": "SAMPLE7Q2Z"
  }'

Response · 201

{
  "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "subscriber": {
    "id": "3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f",
    "account_number": "AL-01042",
    "name": "Wanjiku Kamau",
    "phone": "+254712345678"
  },
  "amount": {
    "amount": "1500.00",
    "currency": "KES"
  },
  "provider": "MPESA",
  "method": "PAYBILL",
  "reference": "SAMPLE7Q2Z",
  "payer_phone": "+254712345678",
  "account_reference": "AL1042",
  "status": "COMPLETED",
  "applied": true,
  "applied_at": "2026-10-25T09:00:05Z",
  "not_applied_amount": {
    "amount": "0.00",
    "currency": "KES"
  },
  "received_at": "2026-10-25T09:00:00Z"
}

Webhooks

Endpoints that receive signed events.

List webhook endpoints#

GET/webhooks

Lists the ISP's webhook endpoints and the events each receives. Signing secrets are not included. Changes nothing.

ScopereadCreator needsSYSTEM:SETTINGS:VIEWRead-only

Responses

200Success. A list of WebhookEndpoint.

Response fields · WebhookEndpoint · 10

Name	Type	Description
`id`	string	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`url`	string	HTTPS URL events are POSTed to. Example: `https://hooks.example.com/coresync`
`description`	string	A note to say what the endpoint is for. Example: `Amani Link CRM`
`events`	array of string	Events this endpoint receives.
`active`	boolean	False when switched off by hand, or automatically after 20 failed attempts in a row. Example: `true`
`disabled_reason`	string	Why it was switched off automatically, if it was.
`last_success_at`	string · date-time	Last successful delivery (UTC). Example: `2026-10-25T09:00:06Z`
`last_failure_at`	string · date-time	Last failed attempt (UTC).
`created_at`	string · date-time	When the endpoint was added (UTC). Example: `2026-10-25T08:00:00Z`
`signing_secret`	string	The secret to verify X-Webhook-Signature with. Present only in the response to `createWebhookEndpoint`; store it then. Example: `whsec_xxx`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/webhooks" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

[
  {
    "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
    "url": "https://hooks.example.com/coresync",
    "description": "Amani Link CRM",
    "events": [
      "payment.received",
      "subscriber.suspended"
    ],
    "active": true,
    "disabled_reason": null,
    "last_success_at": "2026-10-25T09:00:06Z",
    "last_failure_at": null,
    "created_at": "2026-10-25T08:00:00Z",
    "signing_secret": null
  }
]

Get a webhook endpoint#

GET/webhooks/{id}

Returns one endpoint and its delivery health (last success, last failure, whether it was switched off). Changes nothing.

ScopereadCreator needsSYSTEM:SETTINGS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`

idrequiredpath

string · uuid

Endpoint id.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

Responses

200Success. Returns WebhookEndpoint.

Response fields · WebhookEndpoint · 10

Name	Type	Description
`id`	string	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`url`	string	HTTPS URL events are POSTed to. Example: `https://hooks.example.com/coresync`
`description`	string	A note to say what the endpoint is for. Example: `Amani Link CRM`
`events`	array of string	Events this endpoint receives.
`active`	boolean	False when switched off by hand, or automatically after 20 failed attempts in a row. Example: `true`
`disabled_reason`	string	Why it was switched off automatically, if it was.
`last_success_at`	string · date-time	Last successful delivery (UTC). Example: `2026-10-25T09:00:06Z`
`last_failure_at`	string · date-time	Last failed attempt (UTC).
`created_at`	string · date-time	When the endpoint was added (UTC). Example: `2026-10-25T08:00:00Z`
`signing_secret`	string	The secret to verify X-Webhook-Signature with. Present only in the response to `createWebhookEndpoint`; store it then. Example: `whsec_xxx`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/webhooks/2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "url": "https://hooks.example.com/coresync",
  "description": "Amani Link CRM",
  "events": [
    "payment.received",
    "subscriber.suspended"
  ],
  "active": true,
  "disabled_reason": null,
  "last_success_at": "2026-10-25T09:00:06Z",
  "last_failure_at": null,
  "created_at": "2026-10-25T08:00:00Z",
  "signing_secret": null
}

List an endpoint's deliveries#

GET/webhooks/{id}/deliveries

The delivery log for one endpoint, newest first: each event, its status, attempts, the HTTP status the endpoint answered and the last error. Kept for 30 days. Changes nothing.

ScopereadCreator needsSYSTEM:SETTINGS:VIEWRead-only

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`page`query	integer · int32	Page number, starting at 1. Limits: at least 1. Default `1`. Example: `1`
`size`query	integer · int32	Results per page, 1–200. Limits: 1–200. Default `50`. Example: `50`

idrequiredpath

string · uuid

Endpoint id.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

pagequery

integer · int32

Page number, starting at 1.

Limits: at least 1. Default 1.

Example: 1

sizequery

integer · int32

Results per page, 1–200.

Limits: 1–200. Default 50.

Example: 50

Responses

200Success. A page of WebhookDelivery.

Fields of each item · WebhookDelivery · 11

Name	Type	Description
`id`	string	Delivery id; also sent as X-Webhook-Delivery-Id. Example: `8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a`
`endpoint_id`	string	The endpoint. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`event_id`	string	The event's id (the envelope's id). The same event sent to two endpoints has one event_id. Example: `evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9`
`event_type`	string	Event type. Example: `payment.received`
`status`	string	PENDING: waiting for its next attempt. DELIVERED: the endpoint answered 2xx. FAILED: gave up after 5 attempts. One of: `PENDINGDELIVEREDFAILED`
`attempts`	integer · int32	Attempts made so far (at most 5). Example: `1`
`response_status`	integer · int32	HTTP status of the last attempt, if the endpoint answered. Example: `200`
`last_error`	string	What went wrong on the last attempt, if it failed.
`next_attempt_at`	string · date-time	When the next retry happens (UTC), while PENDING.
`created_at`	string · date-time	When the event was queued (UTC). Example: `2026-10-25T09:00:05Z`
`delivered_at`	string · date-time	When the endpoint accepted it (UTC). Example: `2026-10-25T09:00:06Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/webhooks/2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e/deliveries" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "items": [
    {
      "id": "8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
      "endpoint_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "event_id": "evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9",
      "event_type": "payment.received",
      "status": "DELIVERED",
      "attempts": 1,
      "response_status": 200,
      "last_error": null,
      "next_attempt_at": null,
      "created_at": "2026-10-25T09:00:05Z",
      "delivered_at": "2026-10-25T09:00:06Z"
    }
  ],
  "total": 137,
  "page": 1,
  "size": 50
}

Add a webhook endpoint#

POST/webhooks

Adds an HTTPS URL that will receive the chosen events. The response carries the signing secret, the only time it is shown: store it to verify X-Webhook-Signature. Creates a record, so it needs an Idempotency-Key. An ISP can have up to 10 endpoints.

Scopewebhooks:writeCreator needsSYSTEM:SETTINGS:EDITChanges dataIdempotency-Key required

Parameters

Name Type Description

Name	Type	Description
`Idempotency-Key`requiredheader	string	A unique string per new endpoint. Retrying with the same key returns the first response. Example: `4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11`

Idempotency-Keyrequiredheader

string

A unique string per new endpoint. Retrying with the same key returns the first response.

Example: 4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11

Request body

A new webhook endpoint.

Name Type Description

Name	Type	Description
`url`required	string	HTTPS URL to POST events to. Must be reachable from the internet. Limits: up to 500 characters. Example: `https://hooks.example.com/coresync`
`events`required	array of string	Events to receive. One of: `payment.receivedsubscriber.suspendedsubscriber.reactivatedsession.down`
`description`	string	A note to say what it is for. Limits: up to 200 characters. Example: `Amani Link CRM`

urlrequired

string

HTTPS URL to POST events to. Must be reachable from the internet.

Limits: up to 500 characters.

Example: https://hooks.example.com/coresync

eventsrequired

array of string

Events to receive.

One of: payment.receivedsubscriber.suspendedsubscriber.reactivatedsession.down

description

string

A note to say what it is for.

Limits: up to 200 characters.

Example: Amani Link CRM

Responses

201Added. signing_secret is set in this response only. Returns WebhookEndpoint.

Response fields · WebhookEndpoint · 10

Name	Type	Description
`id`	string	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`url`	string	HTTPS URL events are POSTed to. Example: `https://hooks.example.com/coresync`
`description`	string	A note to say what the endpoint is for. Example: `Amani Link CRM`
`events`	array of string	Events this endpoint receives.
`active`	boolean	False when switched off by hand, or automatically after 20 failed attempts in a row. Example: `true`
`disabled_reason`	string	Why it was switched off automatically, if it was.
`last_success_at`	string · date-time	Last successful delivery (UTC). Example: `2026-10-25T09:00:06Z`
`last_failure_at`	string · date-time	Last failed attempt (UTC).
`created_at`	string · date-time	When the endpoint was added (UTC). Example: `2026-10-25T08:00:00Z`
`signing_secret`	string	The secret to verify X-Webhook-Signature with. Present only in the response to `createWebhookEndpoint`; store it then. Example: `whsec_xxx`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameteridempotency_key_required
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
409idempotency_in_progress
422idempotency_key_reusedinvalid_webhook
429rate_limited
500internal_error

What each code means

Example

curl "https://coresyncapi.avitechcloud.com/api/v1/webhooks" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d1c9f0e-7a2b-4f43-9a51-2f0c7c1d8e11" \
  -d '{
    "url": "https://hooks.example.com/coresync",
    "events": [
      "payment.received",
      "subscriber.suspended"
    ],
    "description": "Amani Link CRM"
  }'

Response · 201

{
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "url": "https://hooks.example.com/coresync",
  "description": "Amani Link CRM",
  "events": [
    "payment.received",
    "subscriber.suspended"
  ],
  "active": true,
  "disabled_reason": null,
  "last_success_at": "2026-10-25T09:00:06Z",
  "last_failure_at": null,
  "created_at": "2026-10-25T08:00:00Z",
  "signing_secret": "whsec_xxx"
}

Send a test event to an endpoint#

POST/webhooks/{id}/test

Sends one signed webhook.test event to the endpoint now and returns the delivery, with the HTTP status the endpoint answered. Use it to check a receiver and its signature check. A test is attempted once and never retried; it works on a switched-off endpoint too. Adds one row to the delivery log.

Scopewebhooks:writeCreator needsSYSTEM:SETTINGS:EDITChanges data

Parameters

Name Type Description

Name	Type	Description
`id`requiredpath	string · uuid	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`

idrequiredpath

string · uuid

Endpoint id.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

Responses

200Success. Returns WebhookDelivery.

Response fields · WebhookDelivery · 11

Name	Type	Description
`id`	string	Delivery id; also sent as X-Webhook-Delivery-Id. Example: `8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a`
`endpoint_id`	string	The endpoint. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`event_id`	string	The event's id (the envelope's id). The same event sent to two endpoints has one event_id. Example: `evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9`
`event_type`	string	Event type. Example: `payment.received`
`status`	string	PENDING: waiting for its next attempt. DELIVERED: the endpoint answered 2xx. FAILED: gave up after 5 attempts. One of: `PENDINGDELIVEREDFAILED`
`attempts`	integer · int32	Attempts made so far (at most 5). Example: `1`
`response_status`	integer · int32	HTTP status of the last attempt, if the endpoint answered. Example: `200`
`last_error`	string	What went wrong on the last attempt, if it failed.
`next_attempt_at`	string · date-time	When the next retry happens (UTC), while PENDING.
`created_at`	string · date-time	When the event was queued (UTC). Example: `2026-10-25T09:00:05Z`
`delivered_at`	string · date-time	When the endpoint accepted it (UTC). Example: `2026-10-25T09:00:06Z`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl -X POST "https://coresyncapi.avitechcloud.com/api/v1/webhooks/2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e/test" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 200

{
  "id": "8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
  "endpoint_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "event_id": "evt_test_9a8b7c6d5e4f3a2b",
  "event_type": "webhook.test",
  "status": "DELIVERED",
  "attempts": 1,
  "response_status": 200,
  "last_error": null,
  "next_attempt_at": null,
  "created_at": "2026-10-25T09:00:05Z",
  "delivered_at": "2026-10-25T09:00:06Z"
}

Change a webhook endpoint#

PATCH/webhooks/{id}

Changes the URL, the events, the note, or switches the endpoint off or back on (which also clears an automatic switch-off). Only the fields sent change. The signing secret stays the same.

Scopewebhooks:writeCreator needsSYSTEM:SETTINGS:EDITChanges data

Parameters

Name Type Description

idrequiredpath

string · uuid

Endpoint id.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

Request body

Changes to a webhook endpoint. Only the fields you send change.

Name	Type	Description
`url`	string	New HTTPS URL. Limits: up to 500 characters. Example: `https://hooks.example.com/coresync/v2`
`events`	array of string	The full new list of events (replaces the old list). One of: `payment.receivedsubscriber.suspendedsubscriber.reactivatedsession.down`
`description`	string	New note. Limits: up to 200 characters. Example: `Amani Link CRM (production)`
`active`	boolean	false switches the endpoint off; true switches it back on and clears an automatic disable. Example: `true`

Responses

200Success. Returns WebhookEndpoint.

Response fields · WebhookEndpoint · 10

Name	Type	Description
`id`	string	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`url`	string	HTTPS URL events are POSTed to. Example: `https://hooks.example.com/coresync`
`description`	string	A note to say what the endpoint is for. Example: `Amani Link CRM`
`events`	array of string	Events this endpoint receives.
`active`	boolean	False when switched off by hand, or automatically after 20 failed attempts in a row. Example: `true`
`disabled_reason`	string	Why it was switched off automatically, if it was.
`last_success_at`	string · date-time	Last successful delivery (UTC). Example: `2026-10-25T09:00:06Z`
`last_failure_at`	string · date-time	Last failed attempt (UTC).
`created_at`	string · date-time	When the endpoint was added (UTC). Example: `2026-10-25T08:00:00Z`
`signing_secret`	string	The secret to verify X-Webhook-Signature with. Present only in the response to `createWebhookEndpoint`; store it then. Example: `whsec_xxx`

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
422invalid_webhook
429rate_limited
500internal_error

What each code means

Example

curl -X PATCH "https://coresyncapi.avitechcloud.com/api/v1/webhooks/2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e" \
  -H "X-API-Key: $CORESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/coresync/v2",
    "events": [
      "payment.received",
      "subscriber.suspended",
      "subscriber.reactivated"
    ],
    "description": "Amani Link CRM (production)",
    "active": true
  }'

Response · 200

{
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "url": "https://hooks.example.com/coresync/v2",
  "description": "Amani Link CRM (production)",
  "events": [
    "payment.received",
    "subscriber.suspended",
    "subscriber.reactivated"
  ],
  "active": true,
  "disabled_reason": null,
  "last_success_at": "2026-10-25T09:00:06Z",
  "last_failure_at": null,
  "created_at": "2026-10-25T08:00:00Z",
  "signing_secret": null
}

Delete a webhook endpoint#

DELETE/webhooks/{id}

Deletes the endpoint and its delivery log. Events stop going to it at once; anything still queued is dropped.

Scopewebhooks:writeCreator needsSYSTEM:SETTINGS:EDITChanges data

Parameters

Name Type Description

idrequiredpath

string · uuid

Endpoint id.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

Responses

204Deleted.

Errors

400invalid_requestvalidation_failedmalformed_bodymissing_parameterinvalid_parameter
401missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired
403insufficient_scopekey_owner_lacks_permissiontenant_suspendedtenant_terminated
404not_found
429rate_limited
500internal_error

What each code means

Example

curl -X DELETE "https://coresyncapi.avitechcloud.com/api/v1/webhooks/2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e" \
  -H "X-API-Key: $CORESYNC_API_KEY"

Response · 204 (no body)

HTTP/1.1 204

Objects

The objects the operations return and the events carry. Types link here from every field table.

WebhookEndpoint

A URL that receives events. The signing secret is only returned when the endpoint is created.

Returned by listWebhookEndpoints, getWebhookEndpoint, createWebhookEndpoint, updateWebhookEndpoint.

Name	Type	Description
`id`	string	Endpoint id. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`url`	string	HTTPS URL events are POSTed to. Example: `https://hooks.example.com/coresync`
`description`	string	A note to say what the endpoint is for. Example: `Amani Link CRM`
`events`	array of string	Events this endpoint receives.
`active`	boolean	False when switched off by hand, or automatically after 20 failed attempts in a row. Example: `true`
`disabled_reason`	string	Why it was switched off automatically, if it was.
`last_success_at`	string · date-time	Last successful delivery (UTC). Example: `2026-10-25T09:00:06Z`
`last_failure_at`	string · date-time	Last failed attempt (UTC).
`created_at`	string · date-time	When the endpoint was added (UTC). Example: `2026-10-25T08:00:00Z`
`signing_secret`	string	The secret to verify X-Webhook-Signature with. Present only in the response to `createWebhookEndpoint`; store it then. Example: `whsec_xxx`

WebhookDelivery

One event sent (or being sent) to one endpoint.

Returned by listWebhookDeliveries, sendTestWebhookEvent.

Name	Type	Description
`id`	string	Delivery id; also sent as X-Webhook-Delivery-Id. Example: `8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a`
`endpoint_id`	string	The endpoint. Example: `2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e`
`event_id`	string	The event's id (the envelope's id). The same event sent to two endpoints has one event_id. Example: `evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9`
`event_type`	string	Event type. Example: `payment.received`
`status`	string	PENDING: waiting for its next attempt. DELIVERED: the endpoint answered 2xx. FAILED: gave up after 5 attempts. One of: `PENDINGDELIVEREDFAILED`
`attempts`	integer · int32	Attempts made so far (at most 5). Example: `1`
`response_status`	integer · int32	HTTP status of the last attempt, if the endpoint answered. Example: `200`
`last_error`	string	What went wrong on the last attempt, if it failed.
`next_attempt_at`	string · date-time	When the next retry happens (UTC), while PENDING.
`created_at`	string · date-time	When the event was queued (UTC). Example: `2026-10-25T09:00:05Z`
`delivered_at`	string · date-time	When the endpoint accepted it (UTC). Example: `2026-10-25T09:00:06Z`

Tenant

An ISP on CoreSync.

Name	Type	Description
`code`	string	The ISP's code. Example: `AMANI`
`name`	string	Company name. Example: `Amani Link`
`status`	string	Account status. One of: `PROVISIONINGTRIALACTIVESUSPENDEDCANCELLEDFAILEDTERMINATED`
`currency`	string	ISO 4217 currency the ISP bills in. Example: `KES`
`country_code`	string	ISO 3166-1 alpha-2 country. Example: `KE`
`timezone`	string	IANA time zone the ISP works in. Example: `Africa/Nairobi`

Balance

What a subscriber has paid ahead and what they owe.

Returned by getSubscriberBalance.

Name	Type	Description
`credit`	Money
`outstanding`	Money
`open_invoices`	integer · int32	How many invoices are unpaid. Example: `1`
`next_renewal_amount`	Money
`expires_at`	string · date-time	When the current subscription runs out (UTC). Example: `2026-11-25T09:00:00Z`

Money

An amount of money. The amount is a decimal string with two decimals, so it never loses precision.

Name Type Description

amount

string

Decimal amount as a string.

Example: 1500.00

currency

string

ISO 4217 currency code.

Limits: 3–3 characters, 3 letters.

Example: KES

PlanSummary

A short reference to a plan.

Name	Type	Description
`id`	string	Plan id. Pass it to `changeSubscriberPlan`. Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`
`code`	string	Plan code. Example: `HOME10`
`name`	string	Plan name as customers see it. Example: `Home 10 Mbps`
`price`	Money

Subscriber

A subscriber (an ISP's customer) with their current subscription and balance.

Returned by getSubscriber.

Name	Type	Description
`id`	string	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number. Example: `AL-01042`
`subscriber_code`	string	The billing code the customer types as the M-Pesa paybill account reference. Example: `AL1042`
`username`	string	PPPoE / RADIUS login name. Example: `wanjiku.k`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`first_name`	string	First name. Example: `Wanjiku`
`last_name`	string	Last name. Example: `Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`
`phones`	array of string	Every phone number on the account, in E.164 (some accounts carry two).
`email`	string	Email address, if the ISP has one. Example: `wanjiku@example.com`
`type`	string	Account type. One of: `RESIDENTIALBUSINESSCORPORATE`
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`service_type`	string	How the subscriber connects. One of: `PPPOEHOTSPOTSTATICBOTH`
`address`	string	Installation or physical address. Example: `Kilimani, Nairobi`
`zone`	string	Service zone or area name. Example: `Kilimani`
`online`	boolean	True while the subscriber has a live session. Example: `true`
`last_online_at`	string · date-time	When the subscriber was last seen online (UTC). Example: `2026-10-25T08:55:00Z`
`subscription`	Subscription
`balance`	Balance
`created_at`	string · date-time	When the account was created (UTC). Example: `2025-03-02T10:15:00Z`
`activated_at`	string · date-time	When service was last activated (UTC). Example: `2025-03-02T12:00:00Z`
`suspended_at`	string · date-time	When service was last suspended (UTC), if it is suspended.

SubscriberChange

The result of a change to a subscriber.

Returned by changeSubscriberPlan, suspendSubscriber, reactivateSubscriber.

Name Type Description

outcome

string

done: the change was made. approval_pending: the ISP requires a manager's approval for this action; a request was filed and the change happens when someone approves it in the admin.

One of: doneapproval_pending

subscriber Subscriber

approval_request_id

string

The approval request filed, when outcome is approval_pending.

Subscription

The subscriber's current (or latest) subscription: which plan, and until when.

Name	Type	Description
`id`	string	Subscription id. Example: `5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e`
`status`	string	Subscription status. EXPIRED means the end date passed without a renewal. One of: `PENDINGACTIVEEXPIREDSUSPENDEDCANCELLED`
`plan`	PlanSummary
`starts_at`	string · date-time	Start of the current cycle (UTC). Example: `2026-10-25T09:00:00Z`
`expires_at`	string · date-time	End of the current cycle (UTC). Service stops after this unless renewed. Example: `2026-11-25T09:00:00Z`
`auto_renew`	boolean	Whether the next cycle is taken from wallet credit automatically. Example: `true`
`price`	Money
`pending_plan_id`	string	A plan change scheduled for the next renewal, if any.

Payment

Money received from a customer: M-Pesa, bank, cash or recorded through the API.

Returned by listSubscriberPayments, listPayments, getPayment, recordPayment.

Name	Type	Description
`id`	string	Payment id. Example: `1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f`
`subscriber`	SubscriberRef
`amount`	Money
`provider`	string	Where the money came from, e.g. MPESA, KCB, EQUITY, CASH, BANK. Example: `MPESA`
`method`	string	How it arrived: STK_PUSH, PAYBILL, TILL, MANUAL (recorded by staff or the API). Example: `PAYBILL`
`reference`	string	The provider's receipt / transaction reference. Unique per provider. Example: `SAMPLE7Q2Z`
`payer_phone`	string	The payer's phone in E.164, when the provider gives it. Example: `+254712345678`
`account_reference`	string	What the payer typed as the account / reference. Example: `AL1042`
`status`	string	PENDING, COMPLETED, FAILED or REVERSED. One of: `PENDINGCOMPLETEDFAILEDREVERSED`
`applied`	boolean	True once the money has been credited to the subscriber's wallet / renewal. Example: `true`
`applied_at`	string · date-time	When it was applied (UTC). Example: `2026-10-25T09:00:05Z`
`not_applied_amount`	Money
`received_at`	string · date-time	When the payment was received (UTC). Example: `2026-10-25T09:00:00Z`

SubscriberRef

A short reference to a subscriber.

Name	Type	Description
`id`	string	Subscriber id. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number for this subscriber. Example: `AL-01042`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`

SubscriberSummary

A subscriber as listed. Fetch getSubscriber for the plan, subscription and balance in full.

Returned by listSubscribers, lookupSubscribers.

Name	Type	Description
`id`	string	Subscriber id. Use it in every /subscribers/{id} operation. Example: `3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`account_number`	string	The ISP's account number. Example: `AL-01042`
`subscriber_code`	string	The billing code the customer types as the M-Pesa paybill account reference. Example: `AL1042`
`username`	string	PPPoE / RADIUS login name. Example: `wanjiku.k`
`name`	string	Full name, or the business name for a business account. Example: `Wanjiku Kamau`
`phone`	string	Primary phone number in E.164. Example: `+254712345678`
`email`	string	Email address, if the ISP has one. Example: `wanjiku@example.com`
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`service_type`	string	How the subscriber connects. One of: `PPPOEHOTSPOTSTATICBOTH`
`online`	boolean	True while the subscriber has a live session. Example: `true`
`plan_name`	string	Name of the plan on the current subscription, if any. Example: `Home 10 Mbps`
`expires_at`	string · date-time	When the current subscription runs out (UTC). Example: `2026-11-25T09:00:00Z`
`credit_balance`	Money

Session

A RADIUS session: one connection of a subscriber (PPPoE) or a hotspot device.

Returned by listOnlineSessions.

Name	Type	Description
`id`	string	Session id (RADIUS accounting row id). Example: `4815162342`
`type`	string	PPPOE or HOTSPOT. One of: `PPPOEHOTSPOT`
`username`	string	RADIUS username (PPPoE login, or the voucher / MAC for hotspot). Example: `wanjiku.k`
`subscriber`	SubscriberRef
`ip_address`	string	IP address assigned to the connection. Example: `10.6.0.25`
`mac_address`	string	The device's MAC address, as the router reports it. Example: `AA:BB:CC:DD:EE:FF`
`nas_ip`	string	The router (NAS) the session is on. Example: `10.10.0.1`
`nas_name`	string	The router's name. Example: `Kilimani-CCR`
`started_at`	string · date-time	When the session started (UTC). Example: `2026-10-25T06:12:00Z`
`ended_at`	string · date-time	When it ended (UTC); null while it is live.
`end_cause`	string	Why it ended, as RADIUS reports it (e.g. Lost-Carrier, User-Request, Admin-Reset); null while live.
`duration_seconds`	integer · int64	Length of the session so far, in seconds. Example: `9840`
`bytes_up`	integer · int64	Bytes the subscriber uploaded in this session. Example: `104857600`
`bytes_down`	integer · int64	Bytes the subscriber downloaded in this session. Example: `2147483648`

SubscriberSession

Whether a subscriber is online right now, with their live session or their last one.

Returned by getSubscriberSession.

Name Type Description

online

boolean

True when the subscriber has a live session.

Example: true

current Session

last_session Session

Invoice

An invoice issued to a subscriber.

Returned by listSubscriberInvoices, listInvoices, getInvoice.

Name	Type	Description
`id`	string	Invoice id. Example: `7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d`
`number`	string	Invoice number as printed. Example: `INV-202610-0042`
`subscriber`	SubscriberRef
`plan_name`	string	The plan billed, as it was named when the invoice was issued. Example: `Home 10 Mbps`
`amount`	Money
`status`	string	ISSUED: unpaid. OVERDUE: unpaid past the due date. PAID. VOID: cancelled. One of: `ISSUEDPAIDOVERDUEVOID`
`issued_on`	string · date	Issue date (ISO 8601 date). Example: `2026-10-01`
`due_on`	string · date	Due date (ISO 8601 date). Example: `2026-10-08`
`paid_on`	string · date	Date it was paid, if it was.
`payment_id`	string	The payment that settled it, if any.
`payment_reference`	string	Receipt / reference of the settling payment. Example: `SAMPLE7Q2Z`
`created_at`	string · date-time	When the invoice record was created (UTC). Example: `2026-10-01T05:00:00Z`

Plan

A service plan (package) the ISP sells.

Returned by listPlans, getPlan.

Name	Type	Description
`id`	string	Plan id. Example: `9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f`
`code`	string	Plan code. Example: `HOME10`
`name`	string	Plan name as customers see it. Example: `Home 10 Mbps`
`description`	string	Free-text description. Example: `Unlimited home fibre, 10 Mbps`
`type`	string	FIXED: a home/business line (PPPoE or static). HOTSPOT: a WiFi voucher package. One of: `FIXEDHOTSPOT`
`price`	Money
`validity_value`	integer · int32	Length of one cycle, in validity_unit. Example: `30`
`validity_unit`	string	Unit of the cycle length. One of: `MINUTESHOURSDAYSWEEKSMONTHSYEARS`
`download_mbps`	number · double	Download speed in Mbps, when the plan has a speed profile. Example: `10`
`upload_mbps`	number · double	Upload speed in Mbps, when the plan has a speed profile. Example: `5`
`data_limit_bytes`	integer · int64	Data cap per cycle in bytes; null means unlimited.
`max_devices`	integer · int32	How many devices may be online at once; null uses the ISP default. Example: `1`
`status`	string	Plan status. Only ACTIVE plans can be assigned. One of: `ACTIVEINACTIVEARCHIVED`
`visible`	boolean	Whether customers see the plan on self-service pages. Example: `true`
`created_at`	string · date-time	When the plan was created (UTC). Example: `2026-01-10T07:00:00Z`

Account

Who you are calling as: the API key, and the ISP it acts on.

Returned by getAccount.

Name	Type	Description
`key`	ApiKeyInfo
`tenant`	Tenant

ApiKeyInfo

An API key, as the API sees it. The secret itself is never returned.

Name	Type	Description
`name`	string	The key's name; it is the actor on everything the key does. Example: `amani-crm`
`prefix`	string	The first 12 characters of the key, to tell keys apart. Example: `cs_live_xxxx`
`kind`	string	TENANT for an ISP's own key (cs_live_…). One of: `TENANTPLATFORM`
`scopes`	array of string	What the key may do.
`rate_limit_per_minute`	integer · int32	Requests allowed per minute. Example: `120`
`expires_at`	string · date-time	When the key stops working (UTC); null if it does not expire.

Problem

An error, as RFC 9457 problem details. Branch on code; detail is for people.

Name	Type	Description
`type`required	string	urn:problem:<code>. Example: `urn:problem:not_found`
`title`required	string	Short summary of the kind of problem. Example: `Not found`
`status`required	integer · int32	HTTP status. Example: `404`
`detail`	string	What went wrong, for a person. Example: `Subscriber 3f2a… was not found.`
`instance`	string	The request path. Example: `/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f`
`code`required	string	Stable machine-readable code. Example: `not_found`
`errors`	array of object	Per-field problems, for validation_failed.

PaymentReceivedData

A payment that was received and applied.

Name	Type	Description
`payment`	Payment

PaymentReceivedEvent

Sent when a payment is received and applied to a subscriber.

Name	Type	Description
`id`	string	Event id, unique. The same event delivered twice keeps its id: use it to ignore duplicates. Example: `evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9`
`type`	string	Event type. One of: `payment.received`
`occurred_at`	string · date-time	When it happened (UTC). Example: `2026-10-25T09:00:05Z`
`tenant`	string	The ISP's code. Example: `AMANI`
`data`	PaymentReceivedData

SubscriberStatusData

A subscriber whose service was switched off or back on.

Name	Type	Description
`subscriber`	SubscriberRef
`status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`previous_status`	string	Account status. ACTIVE: connected and billed. SUSPENDED: service off (unpaid, expired or by hand). PENDING / DRAFT: being set up. TERMINATED: closed. One of: `DRAFTPENDINGACTIVESUSPENDEDTERMINATED`
`changed_by`	string	Who made the change: a staff member's name, an API key's name, or SYSTEM for automation and expiry. Example: `SYSTEM`

SubscriberStatusEvent

Sent when a subscriber is suspended (type subscriber.suspended) or reactivated (type subscriber.reactivated).

Name	Type	Description
`id`	string	Event id, unique. Example: `evt_0a1b2c3d4e5f46a7b8c9d0e1f2a3b4c5`
`type`	string	Event type. One of: `subscriber.suspendedsubscriber.reactivated`
`occurred_at`	string · date-time	When it happened (UTC). Example: `2026-10-25T21:00:00Z`
`tenant`	string	The ISP's code. Example: `AMANI`
`data`	SubscriberStatusData

SessionDownData

A PPPoE session that ended.

Name	Type	Description
`session`	Session

SessionDownEvent

Sent when a subscriber's PPPoE session ends.

Name	Type	Description
`id`	string	Event id, unique per session. Example: `evt_sd_4815162342`
`type`	string	Event type. One of: `session.down`
`occurred_at`	string · date-time	When the session ended (UTC). Example: `2026-10-25T08:41:13Z`
`tenant`	string	The ISP's code. Example: `AMANI`
`data`	SessionDownData

WebhookTestData

A test event.

Name Type Description

message

string

Always the same text.

Example: This is a test event from CoreSync.

endpoint_id

string

The endpoint that was tested.

Example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

WebhookTestEvent

Sent by "Send a test event".

Name	Type	Description
`id`	string	Event id. Example: `evt_test_9a8b7c6d5e4f3a2b`
`type`	string	Event type. One of: `webhook.test`
`occurred_at`	string · date-time	When it was sent (UTC). Example: `2026-10-25T09:30:00Z`
`tenant`	string	The ISP's code. Example: `AMANI`
`data`	WebhookTestData

NextWebhooks →

Stuck, or missing something? Tell us what you're building.

hello@coresyncisp.com