The Reporting API gives API users access to every report in the PracBill reports module, so you can pull the same figures the portal shows into your own systems.
Runs a named report and returns its rows. The request body is JSON and you must set the Content-Type: application/json header.
{
"report": "REPORTNAME",
"report_options": {....},
}
| Parameter |
Type |
Required |
Description |
tokenid |
string |
Yes |
Your API access token. |
report |
string |
Yes |
The name of the report in the platform (see Available reports). |
report_options |
object |
Yes |
The options that are required for each report, this varies based on which report you are wanting to generate. You can obtain the information in the html source of the report options entry screen. |
Request
curl https://billing.pracbill.com.au/api/35e1ab32e-3c80-485f-b55b-36d4b3419f32/report \
-X POST -H 'Content-Type: application/json' \
-d '{"report":"agedReceivables","report_options":{"date":"2020-03-29"}}'
Response
Below is an example output from the above report, the core structure remains the same: success: true, data: array.
{
"succes":true,
"data": [
{
"cid":"7777",
"display_name":"INTERNAL USE",
"balance":33.75,
"current":1.25,
"overdue0":2.50,
"overdue30":5,
"overdue60":10,
"overdue90":15
}
]
}
Request with date period
curl https://billing.pracbill.com.au/api/35e1ab32e-3c80-485f-b55b-36d4b3419f32/report \
-X POST -H 'Content-Type: application/json' \
-d '{"report":"paymentsReceived","report_options":{"when":"last month"}}'
Request with custom date range
curl https://billing.pracbill.com.au/api/35e1ab32e-3c80-485f-b55b-36d4b3419f32/report \
-X POST -H 'Content-Type: application/json' \
-d '{"report":"paymentsReceived","report_options":{"when":"custom","date_from":"2024-01-01","date_to":"2024-01-31"}}'
¶ Date handling (the when field)
Most reports support date filtering through the when field and related date parameters. The system provides a helper function that processes these fields and converts them into appropriate date ranges.
The when field accepts predefined time period options that automatically calculate the correct date range:
| Value |
Description |
Date range calculated |
today |
Today's date |
00:00:00 to 23:59:59 today |
yesterday |
Previous day |
00:00:00 to 23:59:59 yesterday |
this week |
Current week |
Monday 00:00 to Sunday 23:59 of current week |
last week |
Previous week |
Monday 00:00 to Sunday 23:59 of previous week |
this month |
Current month |
First day of month to last day of month |
last month |
Previous month |
First day to last day of previous month |
this year |
Current year |
January 1st 00:00:00 to current time |
this quarter |
Current calendar quarter |
First day to last day of current quarter |
last quarter |
Previous calendar quarter |
First day to last day of previous quarter |
custom |
Custom date range |
Uses date_from and date_to fields |
When using when: "custom", you must also provide the fields below. (You do not have to pass the when field if using date_from and date_to fields.)
| Field |
Type |
Description |
date_from |
string |
Start date of the range |
date_to |
string |
End date of the range |
The API accepts dates in two formats:
- Database format (preferred):
YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
- Example:
"2024-03-15" or "2024-03-15 00:00:00"
- Display format:
DD-MM-YYYY
- Example:
"15-03-2024"
- This format is automatically converted to database format
{
"report": "paymentsReceived",
"report_options": {
"when": "last month"
}
}
{
"report": "paymentsReceived",
"report_options": {
"when": "custom",
"date_from": "2024-01-01",
"date_to": "2024-03-31"
}
}
{
"report": "invoiceSummary",
"report_options": {
"when": "custom",
"date_from": "01-01-2024",
"date_to": "31-03-2024"
}
}
Quarters are calculated based on calendar year:
| Quarter |
Date range |
| Q1 |
January 1 to March 31 |
| Q2 |
April 1 to June 30 |
| Q3 |
July 1 to September 30 |
| Q4 |
October 1 to December 31 |
Some reports may support additional sorting options:
| Field |
Type |
Description |
order_by |
string |
Field name to sort results by |
order_by_direction |
string |
Sort direction: asc or desc |
Report name: activeCustomersSummary
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"date":"2020-May",
"new_customers":40,
"end_customers":20,
"total_customers":4082,
}
]
}
| Field |
Brief description |
Notes |
date |
the Year and month of the period YYYY-MMM |
|
new_customers |
the number of new customers for the date |
|
end_customers |
The number of ended customers for the date |
|
total_customers |
The number of total customers for the date |
|
Report name: agedReceivables
| Parameter |
Type |
Required |
Description |
date |
date |
|
The date to do the report at, e.g. 2020-08-01 |
{
"succes":true,
"data": [
{
"cid":"7777",
"display_name":"INTERNAL USE",
"balance":33.75,
"current":1.25,
"overdue0":2.50,
"overdue30":5,
"overdue60":10,
"overdue90":15
"overdue120":0,
}
]
}
| Field |
Brief description |
Notes |
cid |
Customer ID |
|
display_name |
customer display name |
this could be either the company name or the customer first name and last name |
balance |
total owing |
|
current |
owing but not yet due |
|
overdue0 |
1-29 days overdue |
|
overdue30 |
30-59 days overdue |
|
overdue60 |
60-89 days overdue |
|
overdue90 |
90-119 days overdue |
|
overdue120 |
120+ days overdue |
|
Report name: ancilliaryCharges
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"late_fee_count": "211",
"late_fee_amount": "5275.00000",
"payment_fee_count": "187",
"payment_fee_amount": "1050.25840",
"EFT_fee_count": "32",
"EFT_fee_amount": "158.40000"
}
]
}
| Field |
Brief description |
Notes |
late_fee_count |
Number of Late Fees |
|
late_fee_amount |
Ex Tax total of late fees |
|
payment_fee_count |
Number of Credit Card Payment Fees |
|
payment_fee_amount |
Ex Tax total of Credit Card Fees |
|
EFT_fee_count |
CUSTOM Number of fees for this configured type |
These are custom example fields; field names are dynamically generated depending on your settings |
EFT_fee_amount |
CUSTOM Ex Tax total for this configured type |
|
Report name: billedMinutesDetailed
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
ctid |
array |
No |
Call Type Ids, if not specified all call types are returned |
{
"succes":true,
"data": [
{
"call_type":"National Call",
"total_calls":5000,
"total_sms":800,
"billed_minutes":8000,
"billed_amount":444.33
}
]
}
| Field |
Brief description |
Notes |
call_type |
Call Type Name |
|
total_calls |
the number of calls for the time period |
|
total_sms |
the number of sms for the time period |
|
billed_minutes |
The number of billed minutes for the time period |
|
billed_amount |
the $$ rated for those calls and sms |
|
Report name: billedMinutes
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"date":"2020-05-01,
"total_calls":5000,
"billed_minutes":8000,
"total_sms":800,
"billed_amount":444.33
}
]
}
| Field |
Brief description |
Notes |
date |
|
|
total_calls |
the number of calls for the date |
|
billed_minutes |
The number of billed minutes for the date |
|
total_sms |
The number of sms sent on a day |
|
billed_amount |
the $$ rated for those calls and sms |
|
Report name: creditReport
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"date": "2020-05-07",
"cid": "2400000",
"company": "The Risky Customer",
"amount": 27.5,
"description": "Late Fee Credit",
"iid": "222555"
}
]
}
| Field |
Brief description |
Notes |
date |
Date of credit |
|
cid |
Customer ID |
|
company |
Company Name |
|
amount |
Ex-Tax amount of credit |
|
description |
|
|
iid |
Invoice ID credit was applied to |
|
Report name: customerInvoicesServicesCallsSummary
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The Earliest date to include, e.g. 2020-08-01 |
date_to |
date |
|
The Latest date to include |
{
"succes": true,
"data": [
{
"cid": "888555",
"name": "My Example Company",
"invoice_total": 150,
"service_fees": 150,
"usage": 10,
"credits": 11
}
]
}
| Field |
Brief description |
Notes |
cid |
The Customer ID |
|
Name |
The Company Name |
|
Total Invoice |
the inc tax total of the invoice |
|
Services Fees |
the ex tax total of the service fees |
|
Usage |
the ex tax total of the usage |
|
Credits |
the inc tax amount credits |
this is using the simple credit method and does not reflect negative valued items on the invoice |
Report name: customerEndedDetail
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"cid": "123123",
"company": "PracBill",
"accountManager": "",
"serviceTypes": "1300 Number,1800 Phone Number",
"cancellationReason": null,
"lastDate": "2020-05-11",
"avg6monthspend": 1899,
"avgMinutes": 1032,
"avgSms": 0,
}
]
}
| Field |
Brief description |
Notes |
cid |
the customer id |
|
company |
the name of the company |
|
accountManager |
account manager's name |
|
serviceTypes |
a comma separated list of service types that customer had |
|
cancellationReason |
the cancellation reason, if entered |
|
lastDate |
the date the last service ended |
|
avg6monthspend |
the average monthly spend over the last 6 months |
|
avgSms |
the average number of sms sent |
|
Report name: endedServicesDetailed
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
list_price_for_no_price |
boolean |
|
Use List price if monthly fee is $0 |
exclude_billinggroups |
array (strings) |
|
An array of Customer Billing Groups to exclude from the report |
billinggroups |
array (strings) |
|
An array of Customer Billing Groups to ONLY include in the report |
{
"succes":true,
"data": [
{
"enid": "555666",
"customer": "PracBill",
"Account Manager": null,
"avg_account_spend": 50,
"avg_service_spend": 10,
"cancellation_request_date": "2020-04-01",
"churn_reason": "ported away",
"avg_minutes": 50,
"avg_sms": 0,
"start_date": "03-10-2018",
"end_date": "05-05-2020",
"service_type": "1300 Number",
"monthly_fee": "10.00000"
}
]
}
| Field |
Brief description |
enid |
Service ID |
company |
the name of the company |
accountManager |
account manager's name |
avg_account_spend |
average the account spend |
avg_service_spend |
average spend of this service including MRR and usage |
cancellation_request_date |
the date the last service ended |
churn_reason |
the average monthly spend over the last 6 months |
avg_minutes |
average minutes usage per month on this service |
avg_sms |
average number of sms sent per month on this service |
start_date |
service start date |
end_date |
service end date |
service_type |
the type of service it is |
monthlyfee |
ex tax amount of the MRR |
Report name: gpServices
Report information: GP By Service
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest invoice date |
date_to |
date |
|
The latest invoice date |
esid |
array |
|
An array of service types to use, if empty all service types are used |
{
"succes":true,
"data": [
{
"servicetype": "1300 Phone Number",
"service_count": 5,
"monthly_fees": 50
}
]
}
| Field |
Brief description |
Notes |
servicetype |
Service Type |
|
billed_count |
Total Number of Billed Services |
|
service_cost |
The ex tax cost total of the billed services |
|
service_sell |
The ex tax total of the billed services |
|
billed_minutes |
The number of billed minutes for the services |
|
usage_cost |
The ex tax total cost of the usage |
|
usage_sell |
The ex tax total of the sold usage |
|
gp |
The ex tax total of the gross profit for this service type |
|
gp_percent |
The percentage of gross profit for this service type |
|
Report name: salesInvoiceDetail
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The Earliest date to include, e.g. 2020-08-01 |
date_to |
date |
|
The Latest date to include |
{
"succes": true,
"data": [
{
"cid": "888665",
"company": "My Example Company",
"abn": "11 222 333 444",
"name": "John",
"surname": "Doe",
"email": "noreply@email.com",
"address": "11 big street, big town, state, 4455",
"iid": "122345",
"total": "165.00",
"duedate": "2020-04-29",
"dept_name": "PracBill"
}
]
}
| Field |
Brief description |
Notes |
cid |
The Customer ID |
|
Name |
The Company Name |
|
abn |
The ABN of the customer |
|
name |
Customer's First Name |
|
surname |
Customer's last name |
|
email |
Billing Email Address |
|
Address |
Customers address |
|
iid |
the Invoice # |
|
total |
The total inc tax of the invoice |
|
duedate |
The date the invoice is due |
|
dept_name |
The Billing Company |
|
Report name: customerNewDetails
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"cid": "22222222",
"company": "Brand New Customer",
"min_spend": "500.0000",
"contract_length": "",
"expected_revenue": "500.0000",
"monthly_fees": 20,
"setup_fees": null,
"service_types": "1300 Number",
"billinggroup": "Business",
"bundle_fees": null,
"services": [
{
"enid": 1234,
"service_type": "1300 Number",
"service_num": "1300111222",
"start_date": "2020-01-01",
"monthlyfee": "20.00",
}
]
}
]
}
| Field |
Brief description |
Notes |
cid |
Customer ID |
|
compan |
Company Name |
|
min_spend |
Minimum Spend |
field set in customer |
contract_length |
Contract Length |
|
expected_revenue |
Expected Revenue |
field set in customer |
monthly_fees |
Total (Ex-Tax) of the Monthly recurring fees |
|
setup_fees |
Total of misc charges to be applied to customer |
|
service_types |
Comma separated list of service types for customer |
|
billinggroup |
Billing Group |
field set in customer |
bundle_fees |
Total (Ex-Tax) of the monthly bundle fees |
|
services |
An Array of Services |
|
| Field |
Brief description |
Notes |
enid |
Service ID |
|
service_type |
The type of service |
|
service_num |
The service number for the service |
|
strart_date |
The Start date |
|
monthlyfee |
Ex-Tax Monthly recurring fee |
|
Report name: newServicesSalesPersonSummary
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
list_price_for_no_price |
boolean |
|
Use List price if monthly fee is $0 |
{
"succes":true,
"data": [
{
"sales_person": "Average Salesperson",
"total_sales": 5,
"monthly_fees": 50,
"1300 Number": 0,
"1800 Number": 2,
"SIP Account": 3,
}
]
}
| Field |
Brief description |
Notes |
sales_person |
First Name & Last Name of the Salesperson |
|
total_sales |
Total Number of New Services |
|
monthly_fees |
Total (Ex-Tax) of the Monthly recurring fees |
|
[ServiceTypeName] |
The number of sales for that service type |
This is a dynamic field name that populates based on what services sold |
Report name: newServicesSourceSummary
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
list_price_for_no_price |
boolean |
|
Use List price if monthly fee is $0 |
{
"succes":true,
"data": [
{
"source": "Direct",
"total_sales": 5,
"monthly_fees": 50,
"1300 Number": 0,
"1800 Number": 2,
"SIP Account": 3,
}
]
}
| Field |
Brief description |
Notes |
source |
The Name of the source received from |
this is ext_field2 in the service record |
total_sales |
Total Number of New Services |
|
monthly_fees |
Total (Ex-Tax) of the Monthly recurring fees |
|
[ServiceTypeName] |
The number of sales for that service type |
This is a dynamic field name that populates based on what services sold |
Report name: newServices
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
list_price_for_no_price |
boolean |
|
Use List price if monthly fee is $0 |
{
"succes":true,
"data": [
{
"enid":"12341234",
"cid":"555555",
"customer":"Existing Cool Customer",
"start_date":"01-05-2020",
"service_type":"1300 Phone Number",
"monthly_fee":"5.00000",
"newCustomer":false
}
]
}
| Field |
Brief description |
Notes |
enid |
Service ID |
|
cid |
Customer ID |
|
customer |
Customer Name |
|
start_date |
Service Start Date |
|
service_type |
Service Type |
|
monthlyfee |
Ex-Tax Monthly Recurring Fee |
|
newCustomer |
Boolean - New customer |
existing customer is defined as a customer who has at least 1 service before the date_from argument passed in |
Report name: newServicesSummary
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
list_price_for_no_price |
boolean |
|
Use List price if monthly fee is $0 |
{
"succes":true,
"data": [
{
"service_type": "1300 Phone Number",
"service_count": 5,
"monthly_fees": 50
}
]
}
| Field |
Brief description |
Notes |
service_type |
Service Type |
|
service_count |
Total Number of New Services |
|
monthly_fees |
Total (Ex-Tax) of the Monthly recurring fees |
|
new_customers |
The number of new customers |
see below |
existing_customers |
The number of existing customers |
see below |
New and existing customers are the customers that have signed up. If a customer has signed up for multiple service types, then they are only counted once. i.e. a new customer signs up for a "1300 Phone Number" and a "SIP Account": they would only be counted once, and the type they are counted in is random.
Report name: paymentsReceivedAgedReceivables
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for a payment created e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"total":6000,
"current":1000,
"overdue0":1000,
"overdue30":1000,
"overdue60":1000,
"overdue90":1000,
"overdue120":1000,
}
]
}
| Field |
Brief description |
Notes |
total |
The total Amount Received |
|
current |
total applied against owing but not yet due |
|
overdue0 |
total applied against 1-29 days overdue |
|
overdue30 |
total applied against 30-59 days overdue |
|
overdue60 |
total applied against 60-89 days overdue |
|
overdue90 |
total applied against 90-119 days overdue |
|
overdue120 |
total applied against 120+ days overdue |
|
¶ Revenue and payments summary
Report name: summaryRevenuePaymentsReceived
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The Earliest date to include, e.g. 2020-08-01 |
date_to |
date |
|
The Latest date to include |
{
"succes": true,
"data": [
{
"month": "Apr 2020",
"revenue": 50000,
"payments": 45000
}
]
}
| Field |
Brief description |
Notes |
month |
The Month of data |
|
revenue |
the total invoice value |
|
payments |
the total payments received |
|
Report name: engineeringCommissionLiabilityReportDetailed
| Parameter |
Type |
Required |
Description |
date_from |
date |
|
The earliest date to get for the invoice generated e.g. 2020-08-01 |
date_to |
date |
|
The latest date to report until |
{
"succes":true,
"data": [
{
"vid": "7010",
"company": "Cool Supplier",
"vendorgroup": "Dealer",
"enid": "555666",
"service_number": "611300111222",
"amount": 45,
"invoice_date": "2020-07-01",
"iid": "123456"
}
]
}
| Field |
Brief description |
Notes |
vid |
Supplier ID |
|
company |
Supplier Name |
|
vendorgroup |
The reporting group the supplier belongs to |
|
enid |
The service ID |
|
service_number |
The service number |
|
amount |
Amount liable to the supplier |
|
invoice_date |
Date of the invoice |
|
iid |
Invoice ID |
|
Report name: totalServicesSummary
| Parameter |
Type |
Required |
Description |
date_to |
date |
|
The latest date to report until |
exclude_billinggroups |
array (strings) |
|
An array of Customer Billing Groups to exclude from the report |
billinggroups |
array (strings) |
|
An array of Customer Billing Groups to ONLY include in the report |
include_usage |
boolean |
|
include usage for the month of the date_to e.g. date_to = 2020-12-20, the usage would be 2020-12-01 to 2020-12-20 |
serviceTypes |
array (integers) |
|
only include these service types. A list of serviceType IDs can be obtained from Services API |
{
"succes":true,
"data": [
{
"service_type": "1300 Phone Number",
"service_count": 5,
"monthly_fees": 50,
"total_ex_usage": 100,
}
]
}
| Field |
Brief description |
Notes |
service_type |
Service Type |
|
service_count |
Total Number of Services |
|
monthly_fees |
Total (Ex-Tax) of the Monthly recurring fees |
|
total_ex_usage |
Total (Ex-Tax) of the Usage for the month |
only returned when included_usage = true |
Related: Getting started with the API, API overview, Invoices API, Services API.