Customers API

34 PracBill API endpoints for customers. Base URL https://billing.pracbill.com.au/api.

Create a customer (api_key last)

POST /customer/add/{api_key}

Alternative URI for /{api_key}/customer/add with the API token as the final segment. Same handler and behaviour.

Request body

Field	Type	Description
`cid`	integer	Explicit customer id to insert (normally omitted so one is assigned).
`company`	string	Company Name
`name`	string	first name
`surname`	string	last name
`email`	string	customer email address
`mobile`	string	mobile phone contact number
`phone`	string	primary contact number
`web_password`	string	customer portal password (create only, write-only). Stored only as a bcrypt hash and never returned.
`dob`	string	customer date of birth (converted with AppDate::toDBDate, so common date formats are accepted)
`abn`	string	abn for business
`paymethod`	string	the payment method to use ( Invoice, Credit Card, Direct Debit )
`ctgid`	integer	call rates id for this customer, only need if custom rates are required for this customer
`price_book_id`	integer	price book id for this customer. only need if custom prices are required for this customer
`expected_revenue`	number	monthly expected revenue
`minimum_spend`	number	minimum spend requirements
`credit_limit`	number	the total credit limit we should apply to this customer
`terms`	integer	the number of days before an invoice is due
`billinggroup`	string	the billing group
`reseller_cid`	integer	the reseller ( customer id ) that referred this customer
`trading_name`	string	Company Trading Name
`agreement_start`	string	When does the current agreement start
`agreement_end`	string	When does the current agreement end
`currency`	string	The Specific currency to use for this customer, not required if they are using the department default
`do_not_send_invoice`	boolean	set to true to not email invoices to customer
`customers_id`	string	your own external identifier for this customer. Opaque to the platform; not validated or checked for uniqueness. Can also be used in place of the customer id when retrieving a customer.
`bank_name`	string	the name on the bank account
`bank_number`	string	the account number on the bank account
`bank_bsb`	string	the 6 digit bsb on the bank account
`card_token`	string	Gateway card token; stored as the customer's ezypay_id.
`full_address`	string	full address string saved as the customer's primary address ( Address will be looked up using Google )
`create_in_xero`	boolean	When true, the customer is also created in Xero and the response includes xero_id.

Responses

200 — Customer created (or an error envelope with success=false)

Price POS applications and screens

POST /customer/register/applications/{api_key}

Calculate the monthly fee for the requested numbers of applications and screens, plus the setup product. Amounts are number_format strings. Note the API key is the LAST path segment.

Request body

Field	Type	Description
`applicationsRequired`	integer	Number of POS applications/stations
`screensRequired`	integer	Number of screens

Responses

200 — Pricing breakdown

Check a registration for duplicates

POST /customer/register/check/{api_key}

POS self-registration pre-check: fails if the department email already belongs to a customer or the company name already matches a department. Note the API key is the LAST path segment.

Request body

Field	Type	Description
`proposalNumber`	integer	When present the duplicate checks are skipped.
`department`	object

Responses

200 — {success:1} when OK, otherwise an error envelope

Field	Type	Description
`customerDetails`	object

Field	Type	Description
`proposalNumber` required	integer	Quote id (quotes.qid)

Submit a POS registration

POST /customer/register/submit/{api_key}

Creates the customer, a new department (with default POS settings and an initial user), a 'New Customer Registration' helpdesk job, base/setup/application/screen engineering records and the login email. Returns only {success:true}. Note the API key is the LAST path segment.

Request body

Field	Type	Description
`proposalNumber`	integer	When present, the customer is taken from the existing quote instead of being created.
`customerDetails`	object
`paymentDetails`	object
`softwareApplications`	object

Responses

200 — Registration submitted

Create a customer

POST /{api_key}/customer/add

Create a customer. Available at both /{api_key}/customer/add and the alternative form /customer/add/{api_key}. If the API key is configured with create_order, an order and note are also created.

Request body

Field	Type	Description
`cid`	integer	Explicit customer id to insert (normally omitted so one is assigned).
`company`	string	Company Name
`name`	string	first name
`surname`	string	last name
`email`	string	customer email address
`mobile`	string	mobile phone contact number
`phone`	string	primary contact number
`web_password`	string	customer portal password (create only, write-only). Stored only as a bcrypt hash and never returned.
`dob`	string	customer date of birth (converted with AppDate::toDBDate, so common date formats are accepted)
`abn`	string	abn for business
`paymethod`	string	the payment method to use ( Invoice, Credit Card, Direct Debit )
`ctgid`	integer	call rates id for this customer, only need if custom rates are required for this customer
`price_book_id`	integer	price book id for this customer. only need if custom prices are required for this customer
`expected_revenue`	number	monthly expected revenue
`minimum_spend`	number	minimum spend requirements
`credit_limit`	number	the total credit limit we should apply to this customer
`terms`	integer	the number of days before an invoice is due
`billinggroup`	string	the billing group
`reseller_cid`	integer	the reseller ( customer id ) that referred this customer
`trading_name`	string	Company Trading Name
`agreement_start`	string	When does the current agreement start
`agreement_end`	string	When does the current agreement end
`currency`	string	The Specific currency to use for this customer, not required if they are using the department default
`do_not_send_invoice`	boolean	set to true to not email invoices to customer
`customers_id`	string	your own external identifier for this customer. Opaque to the platform; not validated or checked for uniqueness. Can also be used in place of the customer id when retrieving a customer.
`bank_name`	string	the name on the bank account
`bank_number`	string	the account number on the bank account
`bank_bsb`	string	the 6 digit bsb on the bank account
`card_token`	string	Gateway card token; stored as the customer's ezypay_id.
`full_address`	string	full address string saved as the customer's primary address ( Address will be looked up using Google )
`create_in_xero`	boolean	When true, the customer is also created in Xero and the response includes xero_id.

Responses

200 — Customer created (or an error envelope with success=false)

Authenticate a customer or linked contact

POST /{api_key}/customer/authenticate/

authenticate a customer, or a contact (people) linked to exactly one active customer, within the API key's department. Accepts `identifier` (preferred) or `email` (historic field name) — a customer cid, crn_bpay or email address, or a contact's email address — plus `password`. The identifier must resolve to exactly one eligible principal; a customer and a contact sharing an email is ambiguous and fails. On success returns `principal` (the authenticated customer or contact) and `customer` (the owning customer, kept for backwards compatibility — existing integrations can keep reading `customer.cid`). Any failure (wrong password, ambiguous identifier, inactive account, account in another department, unlinked contact) returns the same generic 'Invalid login details.' message so account existence is never revealed. An invalid/unknown API key returns `description: 'invalid key'` instead. A legacy plaintext password is upgraded to bcrypt on successful login. Not written to api_logs (the body carries a password); not rate-limited.

Request body

Field	Type	Description
`identifier`	string	Preferred field name. A customer cid, crn_bpay or email address, or a contact's email address. Takes precedence over email when both are supplied.
`email`	string	Historic field name; same accepted values as identifier. Ignored if identifier is also supplied.
`password` required	string

Responses

200 — Authentication result

Customer balance

GET /{api_key}/customer/balance/{cid}

Returns the current (stored) customer balance.

Responses

200 — Request received successfully

Log external payment

POST /{api_key}/customer/external-payment/{cid}

Log a payment transaction that was processed by an external party or ecommerce solution. Bypasses all credit card validation and authorization since the payment was already processed externally. Requires a transaction_id for refund tracking. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. A repeat of an already-recorded `transaction_id` (same gateway type) returns `success: true` with the existing `payment_id` and the description `Payment already recorded (duplicate transaction_id)`. Failure descriptions: `Invalid key` (note the capital I on this endpoint), `JSON body required`, `Customer not found`, `Amount is required and must be between 0.01 and 99,999,999.99`, `transaction_id is required`, `transaction_id must be between 1 and 255 characters`, `Invalid payment_date format`, `Invoice {n} not found or does not belong to this customer`, `Invoice {n} is voided`, `Failed to record payment`.

Request body

Field	Type	Description
`amount` required	number	Payment amount (must be between 0.01 and 99,999,999.99)
`transaction_id` required	string	External transaction reference ID (max 255 characters). Used for refund tracking and duplicate detection.
`gateway_name`	string	Gateway name for the payment type field (alphanumeric and underscores only). If not specified, uses the department's configured credit card gateway.
`description`	string	Payment description (max 500 characters)
`payment_date`	string	When the payment was processed. Defaults to current time.
`invoice_ids`	array of integer	Specific invoice IDs to apply payment to. If omitted, payment is auto-distributed across unpaid invoices.
`gateway_data`	object	Flexible object for storing external gateway metadata. Reserved keys (processed, message, transaction_id, external) are stripped automatically.

Responses

200 — Payment logged successfully or duplicate detected. Check `success`.
default — Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).

List customers (paginated)

GET /{api_key}/customer/get/page

Get a paginated list of active customers (20 per page). Pagination state is kept server-side per API key (api-{token}-customers.txt table token file). The page segment is optional; /customer/get/page is page 1. Same as /customer/get/page/1.

Responses

200 — Customers retrieved (or an error envelope with success=false)

List customers (paginated)

GET /{api_key}/customer/get/page/{pageNumber}

Responses

200 — Customers retrieved (or an error envelope with success=false)

Service type pricing for a customer

GET /{api_key}/customer/get/servicePricing/{cid}

Get all service types with pricing for a customer (price book prices applied where the customer has a price_book_id).

Responses

200 — Pricing retrieved

Single service type price for a customer

GET /{api_key}/customer/get/servicePricing/{cid}/{esid}

Get specific service type pricing for a customer.

Responses

200 — Pricing retrieved

List a customer's services

GET /{api_key}/customer/get/services/{cid}

Get all services (engineering rows, including ended ones) assigned to a customer.

Responses

200 — Customer services retrieved

Customer statement

GET /{api_key}/customer/get/statement/{cid}

Get the customer statement with the default window start (1 January of the year six months ago) as an inline PDF (default), or as structured JSON when format=json is passed.

Responses

200 — Inline PDF statement, or the JSON statement when format=json (JSON errors also return 200 with success=false; an invalid key returns the JSON error even for the PDF default).

Customer statement from a date

GET /{api_key}/customer/get/statement/{cid}/{date_from}

Get customer statement from a specific date as an inline PDF (default), or as structured JSON when format=json is passed.

Responses

200 — Inline PDF statement, or the JSON statement when format=json (JSON errors also return 200 with success=false; an invalid key returns the JSON error even for the PDF default).

Get a customer

GET /{api_key}/customer/get/{cid}

Get a specific customer with full details (core fields, balance, addresses and the ordinary Customer view fields as stored values). Not found returns {success:false, description:'customer not found'}.

Responses

200 — Customer retrieved (or an error envelope with success=false)

List all active customers

GET /{api_key}/customer/getAll

Get all active (inactive = 0) customers, no pagination. Values are raw database strings.

Responses

200 — All customers retrieved

Get credit management status

GET /{api_key}/customer/getCreditManagementStatus/{cid}

Get credit management status for a customer. Credit management prevents automatic late fees and card charges.

Responses

200 — Request received successfully

Get credit management status

GET /{api_key}/customer/getManagementStatus/{cid}

Get credit management status for a customer. Credit management prevents automatic late fees and card charges. Alias of /customer/getCreditManagementStatus/{cid} (same handler and response).

Responses

200 — Request received successfully

Add a customer charge item

POST /{api_key}/customer/item/add

Add a charge item directly to a customer (customers_iitems).

Request body

Field	Type	Description
`charge_date`	string	Date of the charge (YYYY-MM-DD or DD/MM/YYYY). Defaults to today if omitted
`cid` required	integer	Customer ID (required)
`quantity`	number	Quantity of items. Defaults to 1 if omitted
`pid` required	integer	Product ID (required)
`taxrate_id`	integer	Tax rate ID. Defaults from the product when omitted
`taxrate`	number	Tax rate; always recalculated from the tax rate record, so a supplied value is overridden
`inc_tax_amount`	number	Amount including tax. Defaults from the product when omitted
`description`	string	Description of the charge. Defaults from the product when omitted
`invoice`	integer	Invoice ID the item has been billed on
`deleted`	integer	Soft-delete flag (0/1)
`deptid`	integer	Department id
`iiid`	integer	Related invoice item id
`source`	string	Source of the charge
`orig_id`	string	Caller's original/external id

Responses

200 — Item created (or an error envelope with success=false)

Update a customer charge item

POST /{api_key}/customer/item/update/{id}

Update a customer charge item.

Request body

Field	Type	Description
`charge_date`	string	Date of the charge (YYYY-MM-DD or DD/MM/YYYY)
`cid`	integer	Customer ID
`quantity`	number	Quantity of items
`pid`	integer	Product ID. If supplied, taxrate_id is taken from the product and tax is recalculated
`taxrate_id`	integer	Tax rate ID
`taxrate`	number	Tax rate; always recalculated from the tax rate record, so a supplied value is overridden
`inc_tax_amount`	number	Amount including tax. Supplying it (or pid) recalculates ex_tax_amount and tax
`description`	string	Description of the charge
`invoice`	integer	Invoice ID the item has been billed on
`deleted`	integer	Soft-delete flag (0/1)
`deptid`	integer	Department id
`iiid`	integer	Related invoice item id
`source`	string	Source of the charge
`orig_id`	string	Caller's original/external id

Responses

200 — Item updated (or an error envelope with success=false)

Complete a customer portal password reset

POST /{api_key}/customer/password-reset/confirm

complete a password reset for a customer or linked contact within the API key's department, using a token issued by password-reset/request. Validates that the token is a 64-character lowercase hex string, the password is at least 8 characters, and password/password_confirm match, before consuming the token (exactly once) and writing the new bcrypt (cost 12) hash to customers.web_password or people.web_password. The token must still resolve to an eligible principal in this key's department — unknown, expired, already-used or out-of-department tokens return the same generic invalid/expired message. Not written to api_logs; not rate-limited.

Request body

Field	Type	Description
`token` required	string	The 64-character lowercase hex reset token from the emailed reset link.
`password` required	string	The new password (minimum 8 characters).
`password_confirm` required	string	Must match password.

Responses

200 — Reset result. success is true when the password was reset; otherwise false with a validation-specific message or the generic invalid/expired message.

Request a customer portal password reset

POST /{api_key}/customer/password-reset/request

request a password reset link for a customer or linked contact within the API key's department. Always returns a generic success response so account existence is never revealed. When `email` resolves to exactly one eligible customer or contact, a reset token is issued (1 hour expiry, invalidating any prior unused token for that principal) and the publicwebsite-branded reset email is sent. The link uses the API key's `customer_portal_reset_url` (JSON key data — must be an absolute https URL with no embedded credentials) with `token=` appended as a query parameter, or falls back to the department's public website `/reset-password` page; if neither is available, no email is sent. Not written to api_logs; not rate-limited.

Request body

Field	Type	Description
`email` required	string	The email address to look up.

Responses

200 — Generic success response (returned whether or not an eligible account exists).

Take a payment (or store a card) for a customer

POST /{api_key}/customer/payment/{cid}

Perform a payment on a customer's account using the department's default gateways. The body is read with a plain `json_decode` of the raw request body (no `data=` / url-encoded variants); a missing or invalid body returns `Json body required`. Payment source (first match wins): `payment_method_id` (an explicit saved payment method — see below), `bank_on_file` (latest bank account on file, needs a default direct deposit gateway), `card_on_file` (latest credit card on file, needs a default credit card gateway), otherwise a new card via `payment_token` or ALL of `cc_name`, `cc_number`, `cc_expmonth`, `cc_expyear`, `cc_ccv` (missing ones are reported as `Credit Card Data Missing cc_x,cc_y`). `payment_token` is not available on all gateways, **Payment Token is currently only supported on: Till Payments**. `amount` must be >= 1, unless `amount` is empty and `store_card` is true, in which case the card is only stored on file (`Card On File Updated successfully`). With `store_card` and an amount the card is stored and then charged. The payment is allocated to the customer's unpaid invoices by amount; when there are none a general invoice is created to hold it. `payment_method_id` (PRACBILL-1878) charges one specific saved method (`id` from `GET /{api_key}/customer/{cid}/paymentMethods`) through that method's own gateway rather than the department default, and the resulting payment records the method id. It must be a positive integer, the method must belong to `cid`, be active and not deleted, and its gateway must be configured in the department. It cannot be combined with `store_card`, `card_on_file`, `bank_on_file`, `payment_token` or any `cc_*` field — store a method through the payment-method API first. These checks run before any invoice is created or gateway is called. Failure descriptions: `Json body required`, `Customer not found`, `payment_method_id must be a positive integer`, `payment_method_id cannot be combined with ...`, `Payment method not found`, `Payment gateway for payment method is not available`, `Payment gateway '...' is not configured for this department`, `Payment gateway '...' is not available`, `Payment Method Validation Failed: ...`, `Payment Amount too low, must be greater or equal to 1`, `No payment gateways found`, `No Credit Card Gateway found`, `No Bank Gateway found`, `No Bank On File found`, `No Card On File found`, `Credit Card Data Missing ...`, `Credit Card Validation Failed: ...`, `Credit Card Payment Failed: ...`. On success `description` is `Success`.

Request body

Field	Type	Description
`amount`	number	Amount to charge. Must be >= 1. Leave empty/null/0 together with `store_card: true` to only store the card.
`payment_method_id`	integer	Charge this saved payment method (payment_methods.id) through its own gateway. Must belong to the customer and be active. Takes precedence over every other source and cannot be combined with store_card, card_on_file, bank_on_file, payment_token or cc_* fields.
`bank_on_file`	boolean	Charge the customer's latest bank account on file (requires a default direct deposit gateway on the department). Takes precedence over card_on_file.
`card_on_file`	boolean	Charge the customer's latest credit card on file (requires a default credit card gateway on the department).
`payment_token`	string	A payment/card token to perform the transaction against (also used as the token when `store_card` is true; `card_token` and `token` are accepted as aliases when storing).
`cc_name`	string	The card holder's name
`cc_number`	string	The card number (numeric JSON values are also accepted)
`cc_expmonth`	string	Expiry month (numeric JSON values are also accepted)
`cc_expyear`	string	Expiry year (numeric JSON values are also accepted)
`cc_ccv`	string	The card's ccv (numeric JSON values are also accepted)
`store_card`	boolean	Store this card on file for the customer using the department's default credit card gateway before charging. Card details are taken from payment_token (or card_token / token) or the cc_* fields.
`card_token`	string	Alias of payment_token, only honoured when storing the card (`store_card`).
`token`	string	Alias of payment_token, only honoured when storing the card (`store_card`).

Responses

200 — Request processed. Check `success`.
default — Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).

Get the Customer's current payment details. Card fields (`cc_`) are returned when the customer's best active payment method (primary, then backup, then newest) is a credit card; bank fields (`bank_`) when it is a bank account; neither when there is no active payment method. The card number is masked. Values come straight from the database so numbers are returned as strings.

GET /{api_key}/customer/paymentDetails/{cid}

Responses

200 — Request processed. Check `success`.
default — Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).

Search customers

GET /{api_key}/customer/search/{field}/{value}

Search customers by field. The response is a bare array (no success envelope) of customer records.

Responses

200 — Search results (array) or an error object

Set credit management status

GET /{api_key}/customer/setCreditManagementStatus/{cid}/{status}

Set credit management status for a customer. Declared as a GET in the handler (not POST) and the status is written unvalidated from the URL (documented values 0 or 1). The returned description interpolates the id left on the database handle after the update, so the customer id in the message is unreliable. Requests carry no body.

Responses

200 — Status updated (success=true, description 'Customer {id} set credit_management {status}'), or an error envelope ('invalid key' / 'no customer id')

Set credit management status

GET /{api_key}/customer/setManagementStatus/{cid}/{status}

Responses

200 — Status updated (success=true, description 'Customer {id} set credit_management {status}'), or an error envelope ('invalid key' / 'no customer id')

Update a customer

POST /{api_key}/customer/update/{cid}

Update a customer's details. Success returns {success:true, description:'customer details updated'}. Error envelopes: 'invalid key', 'no customer id', 'invalid customer id', 'No Direct Debit Gateway found', 'No Credit Card Gateway found', 'Failed to store card: ...'. The customer fields are saved before the payment-method store, so a gateway error can follow a successful field update.

Request body

Field	Type	Description
`company`	string	Company Name
`name`	string	first name
`surname`	string	last name
`email`	string	customer email address
`mobile`	string	mobile phone contact number
`dob`	string	customer date of birth (converted with AppDate::toDBDate, so common date formats are accepted)
`abn`	string	abn for business
`paymethod`	string	the payment method to use ( Invoice, Credit Card, Direct Debit )
`ctgid`	integer	call rates id for this customer, only need if custom rates are required for this customer
`price_book_id`	integer	price book id for this customer. only need if custom prices are required for this customer
`expected_revenue`	number	monthly expected revenue
`minimum_spend`	number	minimum spend requirements
`credit_limit`	number	the total credit limit we should apply to this customer
`terms`	integer	the number of days before an invoice is due
`billinggroup`	string	the billing group
`reseller_cid`	integer	the reseller ( customer id ) that referred this customer
`trading_name`	string	Company Trading Name
`agreement_start`	string	When does the current agreement start
`agreement_end`	string	When does the current agreement end
`currency`	string	The Specific currency to use for this customer, not required if they are using the department default
`do_not_send_invoice`	boolean	set to true to not email invoices to customer
`customers_id`	string	your own external identifier for this customer. Opaque to PracBill; not validated or checked for uniqueness. Send an empty string to clear it, omit the property to leave it unchanged. Can also be used in place of the customer id when retrieving a customer.
`bank_name`	string	The name on the bank account. When non-empty, a bank-account payment method is created on the department's default direct debit gateway (together with bank_number and bank_bsb) and set as primary.
`bank_number`	string	the account number on the bank account
`bank_bsb`	string	the 6 digit bsb on the bank account
`card_token`	string	Gateway card token; stored as the customer's ezypay_id AND saved as a new primary payment method on the department's default credit card gateway.
`full_address`	string	full address string saved as the customer's primary address (only when non-empty)
`credit_management`	integer (0 \| 1)	credit management flag
`comments`	string	customer comments
`store_card`	boolean	When truthy, store card details (cc_name, cc_number, cc_expmonth, cc_expyear, cc_ccv) as the primary payment method on the default credit card gateway.
`payment_token`	string	Alternative gateway token for the payment method store (checked before card_token and token).
`token`	string	Alternative gateway token for the payment method store (checked after payment_token and card_token).
`cc_name`	string	Card holder name (used with store_card)
`cc_number`	string	Card number (used with store_card)
`cc_expmonth`	string	Card expiry month (used with store_card)
`cc_expyear`	string	Card expiry year (used with store_card)
`cc_ccv`	string	Card CCV (used with store_card)
`bank_account_name`	string	Alternative bank account name for the payment method store (used when bank_name is empty)
`bank_account_number`	string	Bank account number used with bank_account_name

Responses

200 — Customer updated (or an error envelope with success=false)

Start a Didit identity verification for a customer in the API key's department and return the hosted verification URL. A cid that is not a positive integer returns 400. The customer must belong to the key's department; a missing or foreign customer returns 404 and no verification is started. The body is optional and may only contain document_types (P, DL, HIC, ID, RP); any other field, an unsupported code or a malformed body returns 400. The request is recorded as initiated_via 'signup'. The department must have Didit verification enabled; if it is not configured the backend's 422 is returned, and a provider failure returns 502. An invalid key returns {success:false, description:'invalid key'}.

POST /{api_key}/customer/{cid}/verification

Request body

Field	Type	Description
`document_types`	array of string	Document types the customer may verify with. Omit to use the department workflow's default.

Responses

201 — Verification started
400 — cid is not a positive integer, or the body is malformed or names an unsupported document type
404 — Customer not found in the key's department
422 — Didit verification is not configured for the department
502 — Verification provider or backend unavailable

Read the status of a Didit identity verification owned by the API key's department. A verification that is missing or belongs to another department returns 404 (the two are indistinguishable). Only verification_id, status, document_type and url are returned; the decision result and billing details are internal. A provider failure returns 502. An invalid key returns {success:false, description:'invalid key'}.

GET /{api_key}/verification/{verification_id}

Responses

200 — Verification status
400 — verification_id is not a positive integer
404 — Verification not found in the key's department
422 — Didit verification is not configured for the department
502 — Verification provider or backend unavailable

← All API groups