Skip to content
Sign in Get started
Documentation

9bx user guide

CRM

Sync connections and the Developer API

Keep your clients in step with your billing or customer software, and let other systems talk to 9bx with API keys and webhooks.

Contents: Who can use it · Sync connections · Create a connection · Connection page · The Sync API format guide · API keys and webhooks · Example · FAQ

Who can use it

Administrators with the integration permissions. This area is meant to be set up together with the developer of your other software.

Where: CRM → Clients → Developer API. The button opens the Developer API area with sections API keys, Webhooks and API reference, and the client Sync connections.

Sync connections

A connection links 9bx to one piece of software that holds your clients (billing, ISP management, a CRM). One connection per piece of software. Clients then appear in 9bx and stay up to date.

There are two ways to bring data in. A connection can use either or both:

Method How it works
Webhook Their software sends each client to 9bx the moment it is created, changed or deleted. Always on. 9bx gives the webhook URL and a key (shown once)
API On a schedule, from every 15 minutes to once a day, 9bx calls their API for clients changed since the last read. Their API must ask for a key or password. Turned on per connection, under its API settings

The Connections table shows each connection's name, method, clients, last sync, Webhook calls today, Errors, and status Paused or "Stopped - failing".

Create a connection

  1. Open Clients → Developer API → New connection.
  2. Under Connection give it a name, for example "Billing system".
  3. For the Webhook, no setup is needed: after saving, copy the key and the webhook URL and send them to their developer (code samples in five languages are on the connection page).
  4. To read their API as well, switch on Read clients from their API and fill in:
    • API address: it must start with https://; 9bx calls {address}/clients.
    • How we sign in: API key in Authorization: Bearer; API key in a header (for example X-API-Key); Key in query parameters (?api_key=...); Username and password (Basic); OAuth2 client credentials; or No credentials (open API, with a warning that anyone with the address can read your client list).
    • Secret query parameters and Extra query parameters (not secret, for example branch=dhaka).
    • Pages: Cursor (next_cursor / has_more) or Page numbers (current_page / last_page).
    • How often it reads.
  5. Under Rules choose how new records are matched to existing clients (the customer code is always tried first; two possible clients are never guessed between), what happens when a client is deleted in their software (Make it inactive here or Do nothing), and whether to Add unknown choices to drop-down fields.
  6. Click Create connection.

The connection page

Tab or area What it does
Header Pause / Resume, Sync now, Developer API
Start first import Shown first: check the field mapping, then start. Afterwards changes are read automatically
Cards Clients synced, Pushes today, Open errors, Last activity, Next read, Read up to
Field mapping Where their fields go. Fields already named the 9bx way need no rule; anything not mapped is kept, not lost. Read a sample shows a few records and flags problems. Add a rule maps their field to ours, with value translations (theirs=ours) and a date format. Save and apply updates already-synced clients; Read everything again re-reads all
Settings The API reading options above, and Webhook key with Make a new key (the current key stops working the moment a new one is made)
API reads History of each read
Webhook calls Requests received, with Process again
Errors Records that did not fit, with the reason and a fix: missing required fields, customer code owned by another client, could be more than one client, phone or email held by someone else, a value did not fit its field, unknown status, only an id was sent. You can link the record to a client by number and retry

A client created by a connection shows "Synced from {connection}" and its basic fields are read-only in 9bx (Clients).

The Sync API format guide

On the connection pages an API format section tells their developer exactly what their API must look like. Use Copy or Download as Markdown and send it to them.

It covers:

  • Endpoints: list clients with cursor pages, or numbered pages; optionally one client by ID.
  • Response envelopes for each paging style, and the Client object.
  • Rules:
    • external_id, customer_code and updated_at are required on every record, and external_id never changes.
    • Send deleted: true instead of removing a record, so 9bx learns it is gone.
    • Phone numbers should include the country code, for example +8801711234567.
    • status is one of active, inactive, pending, suspended.
    • Money is an integer in poisha (45.00 BDT is 4500). Dates are YYYY-MM-DD; updated_at is ISO 8601 with a time zone.
    • updated_since is inclusive; sort by updated_at then id so no record falls between pages.
    • HTTPS only.
    • Other field names are fine and can be mapped in the field map.
  • Authentication options and Or push instead: their software can send each change to 9bx itself as the same JSON with the connection's API key.

API keys and webhooks (Developer API)

API keys: one key for each system that calls the 9bx API (billing software, website, shop). New API key: give it a name so you know which to revoke later; pick the scopes (read and write are separate; give only what is needed); optionally Allowed IP addresses (addresses or ranges such as 203.0.113.0/24), Requests a minute, Expires on and a branch. The key is shown once, right after it is created; only a fingerprint is kept. Revoke stops it at once.

Webhooks: New endpoint to have 9bx send events (calls, voicemail, tickets, leads, deals) to your system. Use an https address on the internet. Every payload is signed: the headers X-9bx-Timestamp and X-9bx-Signature carry an HMAC-SHA256 of "timestamp.body" with your signing secret. Tools: Send test, Delivery log (with Send again), New signing secret, Turn off / Turn on. After many failures in a row an endpoint turns itself off; fix the receiver, then turn it on.

API reference: every endpoint with the scope it needs, an example and an OpenAPI file. POST requests accept an Idempotency-Key for safe retries within 24 hours.

Example scenario

A Chattogram ISP wants its billing software and 9bx to share subscribers. The billing vendor's developer receives the Markdown format guide and the webhook URL and key. The admin also switches on Read clients from their API with "Key in query parameters" because the vendor's API uses ?api_key=..., sets the read to every hour, checks the Field mapping (their "package" to the custom field "Plan") and clicks Start first import. Clients appear with the pill "Synced from Billing system".

Tips

  • Create the connection first, mapping later: Read a sample shows real records before you import.
  • Send deletes as deleted: true; do not just remove records.
  • Rotate keys when staff who knew them leave.

Troubleshooting and FAQ

"Stopped - failing". Reading stopped after repeated failures; read the last error, fix the cause, then Resume. Pushes are still accepted meanwhile.

Records show under Errors. Open the error: it names the problem; fix the data or the mapping, then Process again.

Their API is open. Ask their developer for a key; an open API lets anyone read your client list.

A webhook endpoint turned itself off. It failed repeatedly; check the Delivery log, fix the receiver, and turn it on.

I lost the API key. It cannot be shown again; create a new key and revoke the old one.

Clients · Client import · Custom fields