Skip to content

Partner API

Last updated View as Markdown (opens in a new tab)

Use the partner billing API to check balances, move funds to customers, and register and manage customer accounts from your own systems.

The partner API lets your own systems, such as a CRM, website or management software, do billing tasks without signing in to the partner portal. Each request is authenticated with your API key and must come from an allowed IP address.

For your customers’ own API (calls, queues, click-to-call), see API. Your customers need the Integrations licence for every request to their API, including Test API request in the customer portal.

How it works

Section titled “How it works”
  1. Go to Integrations/API › API.
  2. Copy your API key. Send it in the header of every request, with the header name token and the API key as its value.
  3. Click Add IP and add the public IP address your requests come from. Requests from any other IP address are refused with a 403 (forbidden) response.
  4. For each request, the page builds the Full request URL from the parameters you enter, and shows the Header, Header value, Endpoint, Resource and Parameters, each with Copy. Copy them into your request.

Keep your API key secret. Anyone with the key, calling from an allowed IP address, can move funds on your account.

Generate new API Key replaces the key straight away, without asking you to confirm. The old key stops working, so update every system that uses it. The same key is shown as API secret under Settings › Customer Portal › Advanced Site settings, and Generate new token there replaces it too.

Methods

Section titled “Methods”

The page groups the requests:

Group Request What it does
Customer account related requests [GET] Customer balance for period A customer’s balance and charges for a period.
[GET] Customer subscriptions The services a customer is subscribed to.
[GET] Customer billing for period A customer’s billing for a period.
[PUT] Move funds Move funds between your partner account and a customer.
[GET] Customer call plans A customer’s call plans.
Partner account related requests [GET] Partner balance for period Your partner balance for a period.
[GET] List of customers Your customers.
[GET] Equipment The equipment you can sell.
Signup requests [POST] Register customer Register a new customer.
[POST] Confirm customer email Confirm a customer’s email address.
[POST] Log in to customer account Sign a customer in to their account through a URL.
[POST] Reset customer password Reset a customer’s password.

Each request shows its own response codes and what they mean.

Get a customer’s balance

Section titled “Get a customer’s balance”

Enter the start date, end date and customer account number on the page, copy the full request URL and send a GET request with the token header. A successful response looks like this:

{
  "code": 200,
  "data": {
    "opening_balance": 245.71293,
    "payments": 57,
    "adjustments": 5,
    "call_charges": 48.125,
    "other_charges": 7.5,
    "total_charges": 60.625,
    "closing_balance": 242.08793
  }
}

Move funds to or from a customer

Section titled “Move funds to or from a customer”

Copy the request URL from the page and send a PUT request with the token header. Send the parameters in multipart/form-data format. The variable name for each parameter is shown next to it on the page, for example account_number. You need:

  • account_number: the customer’s account number;
  • amount: a positive amount moves funds from you to the customer, a negative amount from the customer to you;
  • description: the reason for the transfer.

A successful response looks like this:

{
  "code": 200,
  "data": {
    "customer_balance": 242.08793,
    "customer_credit_limit": -55
  }
}

Some signup requests need reCAPTCHA

Section titled “Some signup requests need reCAPTCHA”

[POST] Register customer and [POST] Log in to customer account also need a Google reCAPTCHA token in the google_captcha variable. Set up reCAPTCHA on your form by following Google’s documentation, and add your keys under Settings › Customer Portal › Advanced Site settings. See Add and manage customers.

Tips and limits

Section titled “Tips and limits”
  • A 401 response means the token header is missing or the API key is wrong, for example after a new key was generated.
  • A 403 response means the request came from an IP address that isn’t on the allowed list.
  • Test each request with a test customer before you use it on real accounts.
Section titled “Related”