Search, list, create and update customers, read a balance, take a payment and manage a customer's contacts. For developers syncing a CRM or sales portal with PracBill.
Wherever an endpoint takes
:cid, you can pass the customer ID, theaccount_idor thecrm_id.
GET /:tokenid/customer/search/:field/:valueSearch for customers by one field.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
field |
string | Yes | Field to search by: company, name, surname, email, mobile or abn. |
value |
string | Yes | Value to search for. At least 3 characters. |
Response
{
"success": true,
"records": [
{
"company": "Cool Company",
"name": "Very",
"surname": "Important Person",
"email": "vip@vip.com",
"mobile": "0422333444",
"credit_management": 0,
"dob": "1970-01-01",
"abn": "12 123 123 123",
"paymethod": "invoice",
"ctgid": 0
},
{
"company": "Another Company",
"name": "John",
"surname": "Doe",
"email": "john.doe@anothercompany.com",
"mobile": "0456789012",
// Other customer data depending on the search field
}
]
}
GET /:tokenid/customer/getAllReturns every active customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
Response
{
"success": true,
"records": [
{
"cid": 12345,
"company": "Cool Company",
"trading_name": "Cool Inc."
},
{
"cid": 54321,
"company": "Another Company",
"trading_name": null
}
]
}
POST /:tokenid/customer/addCreates a customer from a JSON object.
| Parameter | Type | Required | Description |
|---|---|---|---|
company |
string | Company name. | |
name |
string | First name. | |
surname |
string | Surname. | |
email |
string | Email address. | |
phone |
string | Phone number. | |
mobile |
string | Mobile number. | |
credit_management |
integer | Credit management flag (see Credit management API). | |
web_password |
string | Customer portal password. | |
dob |
date | Date of birth, YYYY-MM-DD. |
|
abn |
string | ABN. | |
paymethod |
string | invoice to pay on invoice, credit card for automated credit card options. |
|
ctgid |
integer | Call rates (rate card) ID to use. | |
card_token |
string | No | Card token to save against the customer; used for offloading card entry screens on public facing portals. |
bank_name |
string | Bank account name. | |
bank_bsb |
string | Bank account BSB. | |
bank_number |
string | Bank account number. |
Request
var myData = {
company: 'Cool Company',
name: 'Very',
surname: 'Important Person',
email: 'vip@vip.com',
phone: '1300vipvip',
mobile: '0422333444',
credit_management: 0,
web_password: '',
dob: '1970-01-01',
abn: '12 123 123 123',
paymethod: 'invoice', // pay on invoice, "credit card" for automated credit card options
ctgid: 0, // call rates id to use
card_token: '', // optional card token to save against the customer, this is used for offloading card entry screens on public facing portals
bank_name: '' // Bank Account Account Name
bank_bsb: '', // Bank Account BSB
bank_number: '', // Bank Account Number
}
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/add',
data: JSON.stringify(myData),
type: 'POST',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"result":'sucess',
"id": 555666,
}
Response (error)
{
"result": "false",
"reason":"no customer found",
"id": 0,
}
POST /:tokenid/customer/update/:cidUpdates an existing customer. The body takes the same fields as create.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | The customer ID to update. |
| body | object | Same fields as Create a customer. |
Request
var myData = {
company: 'Cool Company',
name: 'Very',
surname: 'Important Person',
email: 'vip@vip.com',
phone: '1300vipvip',
mobile: '0422333444',
credit_management: 0,
web_password: '',
dob: '1970-01-01',
abn: '12 123 123 123',
paymethod: 'invoice', // pay on invoice, "credit card" for automated credit card options
ctgid: 0, // call rates id to use
card_token: '', // optional card token to save against the customer, this is used for offloading card entry screens on public facing portals
bank_name: '' // Bank Account Account Name
bank_bsb: '', // Bank Account BSB
bank_number: '', // Bank Account Number
}
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/update/555666',
data: JSON.stringify(myData),
type: 'POST',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
"description": "custoemr details update",
}
Response (error)
{
"result": "false",
"reason":"no customer found",
"id": 0,
}
GET /:tokenid/customer/balance/:cidReturns the current customer balance.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
Response
{
"success": true,
"balance": "333",
"cid": "123345"
}
POST /:tokenid/customer/payment/:cidAdds a payment for a customer, charging the card or bank details on file, a single-use payment token, or card details supplied in the body.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | The customer ID to charge. |
card_on_file |
boolean | Use the card on file. | |
bank_on_file |
boolean | Use the bank details on file. | |
payment_token |
string | (see note 2) | The single use payment token to use. |
cc_name |
string | (see note 1) | Credit card name. |
cc_number |
integer | (see note 1) | Credit card number. |
cc_expmonth |
string | (see note 1) | Credit card expiry month (2 digits with leading 0). |
cc_expyear |
integer | (see note 1) | Credit card expiry year (4 digits). |
cc_ccv |
string | (see note 1) | CCV number of the credit card. |
store_card |
boolean | Update the customer's card on file for future use. | |
amount |
float | Yes | Decimal value to be charged. Must be 1 or more. |
Note 1: supply either one of the *_on_file flags, a payment_token, or all of the card fields.
Note 2: payment_token is not available on all payment gateways. Check that your gateway supports it. Gateways that support payment_token: Till Payments.
Response
{
"success": true,
"description": "Success"
}
GET /:tokenid/customer/:cid/contactsRetrieves all contacts for a customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/1234/contacts',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
"contacts":[
{
"id":"8776",
"first_name":"Peter",
"middle_name":"",
"gender":null,
"last_name":"Pumpkineater",
"dob":"1970-10-31",
"email":"peter@pumpkineater.com",
"web_password":"",
"phone":"1300pumpkin",
"mobile":"0411222333"
}
]
}
Response (error)
{"success":false,"description":"no customer found"}
POST /:tokenid/customer/:cid/contactsAdds a contact to a customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
first_name |
string | First name. | |
last_name |
string | Last name. | |
email |
string | Email address. | |
phone |
string | Phone number. | |
mobile |
string | Mobile number. |
Request
var myData = {
first_name: 'Very',
last_name: 'Important Person',
email: 'vip@vip.com',
phone: '1300vipvip',
mobile: '0422333444',
}
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/1234/contacts',
data: JSON.stringify(myData),
type: 'POST',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
"contact":
{
'first_name': 'Very',
'last_name': 'Important Person',
'email': 'vip@vip.com',
'phone': '1300vipvip',
'mobile': '0422333444',
"id":"8778",
}
}
Response (error)
{"success":false,"description":"no customer found"}
GET /:tokenid/customer/:cid/contact/:contact_idRetrieves one contact.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
contact_id |
integer | Yes | Contact ID. |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/1234/contact/8778',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
"contact":
{
"id":"8778",
"first_name":"Peter",
"middle_name":"",
"gender":null,
"last_name":"Pumpkineater",
"dob":"1970-10-31",
"email":"peter@pumpkineater.com",
"phone":"1300pumpkin",
"mobile":"0411222333"
}
}
Response (error)
{"success":false,"description":"no customer found"}
POST /:tokenid/customer/:cid/contact/:contact_idUpdates one contact. Body fields are the same as create.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
contact_id |
integer | Yes | Contact ID. |
| body | object | first_name, last_name, email, phone, mobile. |
Request
var myData = {
first_name: 'Some',
last_name: 'Guy',
email: 'guy@dude.com',
phone: '1300somegu',
mobile: '0455666777',
}
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/1234/contact/8778',
data: JSON.stringify(myData),
type: 'POST',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
"contact":
{
'first_name': 'Some',
'last_name': 'Important Person',
'email': 'vip@vip.com',
'phone': '1300vipvip',
'mobile': '0422333444',
"id":"8778",
}
}
Response (error)
{"success":false,"description":"no customer found"}
GET /:tokenid/customer/:cid/contact/:contact_id/deleteDeletes one contact.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID (or account_id or crm_id). |
contact_id |
integer | Yes | Contact ID. |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/1234/contact/8778/delete',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":true,
}
Response (error)
{"success":false,"description":"no customer found"}
Related: Getting started with the API, Credit management API, Services API, Invoice API.