Invoice Ninja Octri Preview
GET/api/v1/clients

List clients

GET /api/v1/clients

When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000

/api/v1/clients?balance=gt:1000

You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order

/api/v1/clients?sort=name|desc

You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob"

/api/v1/clients?balance=gt:1000&name=Bob*

If you wish to retrieve child relations, you can also combine the query parameter ?include= with a comma separated list of relationships

/api/v1/clients?include=activities,ledger,system_logs'

The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page

/api/v1/clients?per_page=15&page=2

The default per_page value is 20.

21 parameters
includestringoptional
Include child relationships of the Client Object. ie ?include=documents,system_logs ```html Available includes: contacts [All contacts related to the client] documents [All documents related to the client] gateway_tokens [All payment tokens related to the client] activities [All activities related to the client] ledger [The client ledger] system_logs [System logs related to the client] group_settings [The group settings object the client is assigned to] ``` Usage: ```html /api/v1/clients?include=contacts,documents,activities ```
indexstringoptional
Replaces the default response index from data to a user specific string ie. ```html ?index=new_index ``` response is wrapped ```json { 'new_index' : [ ..... ] } ```
per_pageintegeroptional
The number of records to return for each request, default is 20
pageintegeroptional
The page number to return for this request (when performing pagination), default is 1
statusstringoptional
Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options: - active - archived - deleted ```html GET /api/v1/invoices?status=archived,deleted Returns only archived and deleted invoices ```
created_atintegeroptional
Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp ```html GET /api/v1/invoices?created_at=2022-01-10 Returns entities created on January 10th, 2022 ```
updated_atintegeroptional
Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp ```html GET /api/v1/invoices?updated_at=2022-01-10 Returns entities last updated on January 10th, 2022 ```
is_deletedbooleanoptional
Filters the entity list by entities that have been deleted. ```html GET /api/v1/invoices?is_deleted=true Returns only soft-deleted entities ```
filter_deleted_clientsstringoptional
Filters the entity list and only returns entities for clients that have not been deleted ```html GET /api/v1/invoices?filter_deleted_clients=true Returns only invoices for active (non-deleted) clients ```
namestringoptional
Filter by client name ```html ?name=bob ```
balancestringoptional
Filter by client balance, format uses an operator and value separated by a colon. lt,lte, gt, gte, eq ```html ?balance=lt:10 ``` ie all clients whose balance is less than 10
between_balancestringoptional
Filter between client balances, format uses two values separated by a colon ```html ?between_balance=10:100 ```
emailstringoptional
Filter by client email ```html ?email=bob@gmail.com ```
id_numberstringoptional
Filter by client id_number ```html ?id_number=0001 ```
numberstringoptional
Filter by client number ```html ?number=0002 ```
filterstringoptional
Broad filter which targets multiple client columns: ```html name, id_number, contact.first_name contact.last_name, contact.email, contact.phone custom_value1, custom_value2, custom_value3, custom_value4, ``` ```html ?filter=Bobby ```
sortstringoptional
Returns the list sorted by column in ascending or descending order. Ensure you use column | direction, ie. ```html ?sort=id|desc ```
groupstringoptional
Returns the list of clients assigned to {group_id} ```html ?group=X89sjd8 ```
client_idstringoptional
Returns the list of clients with {client_id} - proxy call to retrieve a client_id wrapped in an array ```html ?client_id=X89sjd8 ```
X-API-TOKENstringrequired
The API token to be used for authentication
X-Requested-Withstringrequired
Used to send the XMLHttpRequest header

6 status codes
200A list of clients
dataarray<object>optional
metaobjectoptional
401Authentication error
messagestringoptional
These credentials do not match our records / Invalid Token
403Authorization error
errorsobjectoptional
messagestringoptional
Insufficient permissions for this resource.
422Validation error
errorsobjectoptional
messagestringoptional
The error message
429Rate Limit Exceeded
errorsobjectoptional
messagestringoptional
Rate limit exceeded.
defaultUnexpected Error
codeintegeroptional
The HTTP error code, ie 5xx 4xx
messagestringoptional
Something terrible went wrong

Error handling

A 401 is returned: Authentication error. A 403 is returned: Authorization error. A 422 is returned: Validation error. A 429 is returned: Rate Limit Exceeded. Any other status is an error: Unexpected Error.