Retrieving, Filtering & Paging of Lists

GET requests follow standard RESTful practices. Our method for retrieving and filtering return data can be applied to any GET endpoints used in our API.

Using the customers endpoint

GET '<https://api.payadvantage.com.au/v3/customers?sort=lastname&isconsumer=true'>

Some endpoints use helpers to simplify filtering. This will be indicated as a unique method within each API section. For example ;

Return Failed Payments list from a particular date

GET '<https://api.payadvantage.com.au/v3/payments_failed/{ddMMyyyy}'>

Query Parameters

Parameters that can be used in request to return filtered or sorted data in the response body. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.

page={page_number} integer
The page number you want returned. {page_number} uses the zero-based index i.e. a value of 0 will return the first page. If the page index is greater than the last page, you will be returned an empty response. Negative indexes will return an error.

per_page={value} integer min = 0, max = 1000
Number of records to view per page. By default the {value} is 100. Values greater than the max, or negative values will return an error.

sort={x,-y,z} string array
Let's you sort by a defined set of parameters based on the endpoint. A minus symbol (-) in front of the parameter name will sort by descending order e.g. /customer?sort=lastname,-dob

Check the query parameters for each API to see what parameters can be used with the sort function. Parameter names are case insensitive and don't contain spaces. If you include an invalid parameter name, an error will be returned.

{parameter}={value} Parameter Dependent
Let's you filter data by parameter values. Check the query parameters for each endpoint to see what parameters can be used with the sort function. Parameter names are case insensitive and don't contain spaces. If you include an invalid parameter name, an error will be returned.

Example Request - Return List of Business type customers sorted by Name (A-Z)

curl -L -X GET '.../v3/customers?sort=name&isconsumer=false'  
 -H 'Authorization: Bearer {access_token}'  
Bash  

Response

STATUS 200 // Successful

{  
	"Records": [  
		{  
			"Code": "ABC123",  
			"ExternalID": "ABC001",  
			"IsConsumer": false,  
			"DateJoined": "2013-09-13T14:10:31.247",  
			"Name": "Apples Inc.",  
			"...": ...  
		},  
		{  
			"Code": "DEF456",  
			"ExternalID": "ABC002",  
			"IsConsumer": false,  
			"DateJoined": "2011-05-28T11:03:24.128",  
			"Name": "Bananas Org.",  
			"...": ...  
		},  
		{  
    	...  
		}  
	],  
	"Meta":  
	{  
		"page": 0,  
		"recs_per_page": 100,  
		"total_recs": 328  
	}  
}

Paging of Data

When dealing with list data we page this for speed and efficiency. You can see the number of records, pages and records per page by inspecting the returned meta object in the response.

Example

{"Meta": { "page": 1, "recs_per_page": 15, "total_recs": 75 }}

By default we will return 100 records per page and you can increase this to a maximum of 1000 by appending the recs_per_page parameter to the query string when retrieving a list.

Example

.../v3/customers?recs_per_page=500

We strongly recommend that you don't simply increase the page length simply to avoid the necessary coding for handling pages.

Once you have enumerated the initial page you can retrieve subsequent pages by appending the page parameter to the query string. Note this uses the zero-based index i.e. a value of 0 will return the first page

Example

.../v3/customers?page=1