API reference
Customers
Customers are the people and companies the organization bills. Create them once with your own reference, keep them up to date, and read their services and statement totals.
| Endpoint | What it does |
|---|---|
POST /api/v1/customers | Create a customer |
PATCH /api/v1/customers/{id} | Update a customer |
GET /api/v1/customers/{id} | Get a customer |
GET /api/v1/customers | List customers |
GET /api/v1/customers/{id}/enrollments | List a customer's enrollments |
GET /api/v1/customers/{id}/statement | Get a customer's statement |
The customer object#
Someone the organization bills: an individual or a company.
| Field | Description |
|---|---|
| idinteger | Flux's id for the customer. |
| externalRefstring · nullable | Your id for the customer, such as a workspace id. Unique within the organization. |
| customerTypestring | individual or company. |
| namestring | The billing name. For a company, the legal name, else the company name. For an individual, their name. |
| legalNamestring · nullable | Registered legal name. |
| companyNamestring · nullable | Trading name. Set for companies. |
| firstNamestring · nullable | Set for individuals. |
| lastNamestring · nullable | Set for individuals. |
| emailstring | The customer's email. Gets invoices when there's no primary contact. |
| phonestring · nullable | In international format. |
| addressstring · nullable | Postal address. |
| taxIdstring · nullable | Tax identification number (TIN). Unique within the organization. |
| vatNumberstring · nullable | VAT registration number. |
| rcNumberstring · nullable | CAC registration (RC) number. |
| parentCustomerIdinteger · nullable | The group company this customer belongs to, in the same organization. |
| regulatedEntityCountinteger · nullable | Number of regulated entities. 0 or more. |
| defaultCurrencystring · nullable | Pre-fills the currency when someone raises an invoice for this customer in the Flux app. One of NGN, USD, CAD, EUR, GBP. |
| defaultSettlementBankIdinteger · nullable | The organization's bank account that this customer's payments settle into. Ids come from the Flux app. |
| contactsarray of Billing contact · nullable | Billing contacts. Returned by get, create and update. Always null in list results. |
| createdAttimestamp | When the customer was created. Server time, no offset. |
| updatedAttimestamp · nullable | When the customer last changed. null if never. |
{
"id": 812,
"externalRef": "ws_42",
"customerType": "company",
"name": "Leadway Group Plc",
"legalName": "Leadway Group Plc",
"companyName": "Leadway Group",
"firstName": null,
"lastName": null,
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"parentCustomerId": null,
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"defaultSettlementBankId": null,
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"phone": null,
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"phone": null,
"isBillingPrimary": false,
"ccOnInvoices": true
}
],
"createdAt": "2026-11-01T10:20:00",
"updatedAt": null
}The billing contact object#
An email on a customer that receives invoices and receipts.
Who gets invoice and receipt emails: the primary contact (or the customer's email when there's no primary contact), plus every contact with ccOnInvoices. Duplicates are removed.
| Field | Description |
|---|---|
| namestring · nullable | Label or person's name. |
| emailstring | Receives invoices and receipts. |
| phonestring · nullable | Phone number. |
| isBillingPrimaryboolean | The primary billing contact. At most one per customer. |
| ccOnInvoicesboolean | Copied on invoice and receipt emails. |
The enrollment object#
A customer's subscription to a service in the organization's catalogue.
Enrollments are managed in the Flux app; the API reads them.
| Field | Description |
|---|---|
| idinteger | Enrollment id. |
| serviceIdinteger | The service in the organization's catalogue. |
| serviceNamestring · nullable | The service's name. |
| amountnumber (decimal) | The agreed amount, else the service's price. Major units. |
| enrolledFromdate | Start date. |
| enrolledTodate · nullable | End date. null if open-ended. |
| activeboolean | Active and within its dates today. |
{
"id": 31,
"serviceId": 7,
"serviceName": "Subscription",
"amount": 250000.00,
"enrolledFrom": "2026-10-01T00:00:00",
"enrolledTo": null,
"active": true
}The statement object#
Open, overdue and paid totals per currency. Counts approved and paid invoices; voided ones are excluded.
| Field | Description |
|---|---|
| customerIdinteger | The customer. |
| currenciesarray of Currency totals | One entry per currency the customer has invoices in. Empty if none. |
Each entry in currencies:
| Field | Description |
|---|---|
| currencystring | ISO currency code. One of NGN, USD, CAD, EUR, GBP. |
| opennumber (decimal) | Total of approved, unpaid invoices. Includes the overdue ones. |
| overduenumber (decimal) | Total of open invoices past their due date. |
| paidnumber (decimal) | Total of paid invoices. |
| openCountinteger | Number of open invoices. |
| overdueCountinteger | Number of overdue invoices. |
| paidCountinteger | Number of paid invoices. |
{
"customerId": 812,
"currencies": [
{
"currency": "NGN",
"open": 500000.00,
"overdue": 250000.00,
"paid": 1250000.00,
"openCount": 2,
"overdueCount": 1,
"paidCount": 5
}
]
}Create a customer#
POST
/api/v1/customersCreates a customer. Send an Idempotency-Key so a retry can't create a second one.
Request body
| Field | Description |
|---|---|
| customerTypestring | optional individual or company. Defaults to individual on create. |
| emailstring | required A valid email address. Required on create. |
| firstNamestring | optional Required for individuals. |
| lastNamestring | optional Required for individuals. |
| phonestring | optional Required and must be valid for individuals. Optional for companies, but must be valid if sent. |
| companyNamestring | optional Required for companies. |
| legalNamestring | optional Registered legal name. Used as the billing name when set. |
| addressstring | optional Postal address. |
| taxIdstring | optional TIN. Another customer in the organization can't have the same one. |
| vatNumberstring | optional VAT registration number. |
| rcNumberstring | optional CAC registration (RC) number. |
| externalRefstring | optional Your id for the customer. At most 100 characters, unique within the organization. |
| parentCustomerIdinteger | optional A customer in the same organization. Can't be the customer itself, or a customer whose parent is this one. |
| regulatedEntityCountinteger | optional 0 or more. |
| defaultCurrencystring | optional A supported currency code. One of NGN, USD, CAD, EUR, GBP. |
| defaultSettlementBankIdinteger | optional One of the organization's bank account ids, from the Flux app. |
| contactsarray of Billing contact (request) | optional At most 20, each with a valid email, and at most one primary. On update, sending contacts replaces the whole list. Leave it out to keep the current contacts. |
Validation follows the Flux app. email is always required. Individuals need firstName, lastName and a valid phone. Companies need companyName. A 409 conflict means another customer in the organization already has the same externalRef, the same taxId, or the same name and email.
Request
curl -X POST "$FLUX_BASE_URL/api/v1/customers" \
-H "Authorization: ApiKey $FLUX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-customer-ws_42" \
-d '{
"customerType": "company",
"companyName": "Leadway Group",
"legalName": "Leadway Group Plc",
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"externalRef": "ws_42",
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"isBillingPrimary": false,
"ccOnInvoices": true
}
]
}'// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers`, {
method: "POST",
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "create-customer-ws_42",
},
body: JSON.stringify({
customerType: "company",
companyName: "Leadway Group",
legalName: "Leadway Group Plc",
email: "finance@leadway.example",
phone: "+2348012345678",
address: "121 Funso Williams Ave, Lagos",
taxId: "12345678-0001",
vatNumber: "VAT-001",
rcNumber: "RC123456",
externalRef: "ws_42",
regulatedEntityCount: 3,
defaultCurrency: "NGN",
contacts: [
{
name: "Finance",
email: "finance@leadway.example",
isBillingPrimary: true,
ccOnInvoices: false,
},
{
name: "CFO",
email: "cfo@leadway.example",
isBillingPrimary: false,
ccOnInvoices: true,
},
],
}),
});
console.log(response.status, await response.json());import os
import requests
response = requests.post(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers",
headers={
"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}",
"Idempotency-Key": "create-customer-ws_42",
},
json={
"customerType": "company",
"companyName": "Leadway Group",
"legalName": "Leadway Group Plc",
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"externalRef": "ws_42",
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"isBillingPrimary": True,
"ccOnInvoices": False,
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"isBillingPrimary": False,
"ccOnInvoices": True,
},
],
},
timeout=30,
)
print(response.status_code, response.json())<?php
$body = <<<'JSON'
{
"customerType": "company",
"companyName": "Leadway Group",
"legalName": "Leadway Group Plc",
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"externalRef": "ws_42",
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"isBillingPrimary": false,
"ccOnInvoices": true
}
]
}
JSON;
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: create-customer-ws_42',
],
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/customers");
request.Headers.Add("Idempotency-Key", "create-customer-ws_42");
request.Content = new StringContent("""
{
"customerType": "company",
"companyName": "Leadway Group",
"legalName": "Leadway Group Plc",
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"externalRef": "ws_42",
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"isBillingPrimary": false,
"ccOnInvoices": true
}
]
}
""", Encoding.UTF8, "application/json");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"customerType": "company",
"companyName": "Leadway Group",
"legalName": "Leadway Group Plc",
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"externalRef": "ws_42",
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"isBillingPrimary": false,
"ccOnInvoices": true
}
]
}`)
req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "create-customer-ws_42")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
201 Created
{
"id": 812,
"externalRef": "ws_42",
"customerType": "company",
"name": "Leadway Group Plc",
"legalName": "Leadway Group Plc",
"companyName": "Leadway Group",
"firstName": null,
"lastName": null,
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"parentCustomerId": null,
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"defaultSettlementBankId": null,
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"phone": null,
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"phone": null,
"isBillingPrimary": false,
"ccOnInvoices": true
}
],
"createdAt": "2026-11-01T10:20:00",
"updatedAt": null
}8 possible errors
| Status | Code | When |
|---|---|---|
400 | invalid_request | Validation failed. The message says what, such as Add at least one invoice item. |
409 | conflict | A uniqueness rule failed, such as another customer having the same externalRef. |
400 | invalid_idempotency_key | Idempotency-Key is longer than 255 characters. |
409 | idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_key_reused | The same Idempotency-Key was sent with a different request. |
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |
Update a customer#
PATCH
/api/v1/customers/{id}Changes only the fields you send. Sending contacts replaces the whole list; leave it out to keep the current contacts.
Path parameters
| Field | Description |
|---|---|
| idinteger | required The customer's id. |
Request body
| Field | Description |
|---|---|
| customerTypestring | optional individual or company. Defaults to individual on create. |
| emailstring | optional A valid email address. Required on create. |
| firstNamestring | optional Required for individuals. |
| lastNamestring | optional Required for individuals. |
| phonestring | optional Required and must be valid for individuals. Optional for companies, but must be valid if sent. |
| companyNamestring | optional Required for companies. |
| legalNamestring | optional Registered legal name. Used as the billing name when set. |
| addressstring | optional Postal address. |
| taxIdstring | optional TIN. Another customer in the organization can't have the same one. |
| vatNumberstring | optional VAT registration number. |
| rcNumberstring | optional CAC registration (RC) number. |
| externalRefstring | optional Your id for the customer. At most 100 characters, unique within the organization. |
| parentCustomerIdinteger | optional A customer in the same organization. Can't be the customer itself, or a customer whose parent is this one. |
| regulatedEntityCountinteger | optional 0 or more. |
| defaultCurrencystring | optional A supported currency code. One of NGN, USD, CAD, EUR, GBP. |
| defaultSettlementBankIdinteger | optional One of the organization's bank account ids, from the Flux app. |
| contactsarray of Billing contact (request) | optional At most 20, each with a valid email, and at most one primary. On update, sending contacts replaces the whole list. Leave it out to keep the current contacts. |
Request
curl -X PATCH "$FLUX_BASE_URL/api/v1/customers/812" \
-H "Authorization: ApiKey $FLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+2348098765432",
"regulatedEntityCount": 4
}'// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers/812`, {
method: "PATCH",
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
phone: "+2348098765432",
regulatedEntityCount: 4,
}),
});
console.log(response.status, await response.json());import os
import requests
response = requests.patch(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers/812",
headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
json={
"phone": "+2348098765432",
"regulatedEntityCount": 4,
},
timeout=30,
)
print(response.status_code, response.json())<?php
$body = <<<'JSON'
{
"phone": "+2348098765432",
"regulatedEntityCount": 4
}
JSON;
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers/812');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Patch, $"{baseUrl}/api/v1/customers/812");
request.Content = new StringContent("""
{
"phone": "+2348098765432",
"regulatedEntityCount": 4
}
""", Encoding.UTF8, "application/json");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"phone": "+2348098765432",
"regulatedEntityCount": 4
}`)
req, err := http.NewRequest("PATCH", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers/812", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
200 OK
{
"id": 812,
"externalRef": "ws_42",
"customerType": "company",
"name": "Leadway Group Plc",
"legalName": "Leadway Group Plc",
"companyName": "Leadway Group",
"firstName": null,
"lastName": null,
"email": "finance@leadway.example",
"phone": "+2348098765432",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"parentCustomerId": null,
"regulatedEntityCount": 4,
"defaultCurrency": "NGN",
"defaultSettlementBankId": null,
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"phone": null,
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"phone": null,
"isBillingPrimary": false,
"ccOnInvoices": true
}
],
"createdAt": "2026-11-01T10:20:00",
"updatedAt": "2026-11-08T16:45:00"
}6 possible errors
| Status | Code | When |
|---|---|---|
400 | invalid_request | Validation failed. The message says what, such as Add at least one invoice item. |
404 | not_found | Unknown id, or an id that belongs to another organization. |
409 | conflict | A uniqueness rule failed, such as another customer having the same externalRef. |
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |
Get a customer#
GET
/api/v1/customers/{id}Returns the customer with its billing contacts.
Path parameters
| Field | Description |
|---|---|
| idinteger | required The customer's id. |
Request
curl "$FLUX_BASE_URL/api/v1/customers/812" \
-H "Authorization: ApiKey $FLUX_API_KEY"// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers/812`, {
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
},
});
console.log(response.status, await response.json());import os
import requests
response = requests.get(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers/812",
headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers/812');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/customers/812");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers/812", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
200 OK
{
"id": 812,
"externalRef": "ws_42",
"customerType": "company",
"name": "Leadway Group Plc",
"legalName": "Leadway Group Plc",
"companyName": "Leadway Group",
"firstName": null,
"lastName": null,
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"parentCustomerId": null,
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"defaultSettlementBankId": null,
"contacts": [
{
"name": "Finance",
"email": "finance@leadway.example",
"phone": null,
"isBillingPrimary": true,
"ccOnInvoices": false
},
{
"name": "CFO",
"email": "cfo@leadway.example",
"phone": null,
"isBillingPrimary": false,
"ccOnInvoices": true
}
],
"createdAt": "2026-11-01T10:20:00",
"updatedAt": null
}4 possible errors
| Status | Code | When |
|---|---|---|
404 | not_found | Unknown id, or an id that belongs to another organization. |
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |
List customers#
GET
/api/v1/customersLists customers, newest first. Filter by externalRef to find the customer you created for one of your records. List results have contacts: null; get the customer to read its contacts.
Query parameters
| Field | Description |
|---|---|
| externalRefstring | Only the customer with this reference. |
| limitinteger | Items per page, 1 to 100. Default 25. |
| cursorstring | The nextCursor from the previous page. Leave it out for the first page. |
Request
curl "$FLUX_BASE_URL/api/v1/customers?externalRef=ws_42" \
-H "Authorization: ApiKey $FLUX_API_KEY"// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers?externalRef=ws_42`, {
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
},
});
console.log(response.status, await response.json());import os
import requests
response = requests.get(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers",
headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
params={
"externalRef": "ws_42",
},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers?externalRef=ws_42');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/customers?externalRef=ws_42");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers?externalRef=ws_42", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
200 OK
A page of customers. An empty data array means no match.
{
"data": [
{
"id": 812,
"externalRef": "ws_42",
"customerType": "company",
"name": "Leadway Group Plc",
"legalName": "Leadway Group Plc",
"companyName": "Leadway Group",
"firstName": null,
"lastName": null,
"email": "finance@leadway.example",
"phone": "+2348012345678",
"address": "121 Funso Williams Ave, Lagos",
"taxId": "12345678-0001",
"vatNumber": "VAT-001",
"rcNumber": "RC123456",
"parentCustomerId": null,
"regulatedEntityCount": 3,
"defaultCurrency": "NGN",
"defaultSettlementBankId": null,
"contacts": null,
"createdAt": "2026-11-01T10:20:00",
"updatedAt": null
}
],
"nextCursor": null,
"hasMore": false
}3 possible errors
| Status | Code | When |
|---|---|---|
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |
List a customer's enrollments#
GET
/api/v1/customers/{id}/enrollmentsThe services the customer is enrolled in: their current plan. Returns an array, newest first, not a page.
Path parameters
| Field | Description |
|---|---|
| idinteger | required The customer's id. |
This endpoint doesn't return billingCycle or nextBillingDate yet. The enrollment webhook object does. See Known limitations.
Request
curl "$FLUX_BASE_URL/api/v1/customers/812/enrollments" \
-H "Authorization: ApiKey $FLUX_API_KEY"// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers/812/enrollments`, {
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
},
});
console.log(response.status, await response.json());import os
import requests
response = requests.get(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers/812/enrollments",
headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers/812/enrollments');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/customers/812/enrollments");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers/812/enrollments", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
200 OK
[
{
"id": 31,
"serviceId": 7,
"serviceName": "Subscription",
"amount": 250000.00,
"enrolledFrom": "2026-10-01T00:00:00",
"enrolledTo": null,
"active": true
}
]4 possible errors
| Status | Code | When |
|---|---|---|
404 | not_found | Unknown id, or an id that belongs to another organization. |
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |
Get a customer's statement#
GET
/api/v1/customers/{id}/statementOpen, overdue and paid totals per currency, for a billing page or a credit check. Counts approved and paid invoices; voided ones are excluded.
Path parameters
| Field | Description |
|---|---|
| idinteger | required The customer's id. |
Request
curl "$FLUX_BASE_URL/api/v1/customers/812/statement" \
-H "Authorization: ApiKey $FLUX_API_KEY"// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/customers/812/statement`, {
headers: {
Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
},
});
console.log(response.status, await response.json());import os
import requests
response = requests.get(
f"{os.environ['FLUX_BASE_URL']}/api/v1/customers/812/statement",
headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/customers/812/statement');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;using System.Net.Http.Headers;
var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/customers/812/statement");
using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/customers/812/statement", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(out))
}Responses
200 OK
{
"customerId": 812,
"currencies": [
{
"currency": "NGN",
"open": 500000.00,
"overdue": 250000.00,
"paid": 1250000.00,
"openCount": 2,
"overdueCount": 1,
"paidCount": 5
}
]
}4 possible errors
| Status | Code | When |
|---|---|---|
404 | not_found | Unknown id, or an id that belongs to another organization. |
401 | unauthorized | No API key, an unknown key or a revoked key. |
403 | insufficient_scope | The key lacks the scope. details names it: { "required": "invoices:write" }. |
429 | rate_limited | Too many requests for this key. Wait for the Retry-After seconds. |