Sultan
/
invoiceninja
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Migrate API docs to Scalar

This commit is contained in:
David Bomba 2024-11-18 10:43:50 +11:00
parent f49fa617b5
commit 94735d1fa0
8 changed files with 917 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
app/Filters/ClientFilters.php
View File

@ -152,21 +152,6 @@ class ClientFilters extends QueryFilters
}); });
// return $this->builder->where(function ($query) use ($filter) {
// $query->where('name', 'like', '%'.$filter.'%')
// ->orWhere('id_number', 'like', '%'.$filter.'%')
// ->orWhere('number', 'like', '%'.$filter.'%')
// ->orWhereHas('contacts', function ($query) use ($filter) {
// $query->where('first_name', 'like', '%'.$filter.'%');
// $query->orWhere('last_name', 'like', '%'.$filter.'%');
// $query->orWhere('email', 'like', '%'.$filter.'%');
// $query->orWhere('phone', 'like', '%'.$filter.'%');
// })
// ->orWhere('custom_value1', 'like', '%'.$filter.'%')
// ->orWhere('custom_value2', 'like', '%'.$filter.'%')
// ->orWhere('custom_value3', 'like', '%'.$filter.'%')
// ->orWhere('custom_value4', 'like', '%'.$filter.'%');
// });
} }
/** /**

496
openapi/api-docs.yaml
View File

@ -179,7 +179,7 @@ paths:
label: curl label: curl
source: | source: |
curl --request POST \ curl --request POST \
--url 'https://invoicing.co/api/v1/login?include=company,token' \ --url 'https://demo.invoiceninja.com/api/v1/login?include=company,token' \
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'X-Requested-With: XMLHttpRequest' \ --header 'X-Requested-With: XMLHttpRequest' \
--header 'Accept: application/json' --header 'Accept: application/json'
@ -12704,7 +12704,12 @@ paths:
label: php label: php
source: | source: |
$ninja = new InvoiceNinja("your_token"); $ninja = new InvoiceNinja("your_token");
$invoices = $ninja->clients->all(); $invoices = $ninja->clients->all([
'balance' => 'lt:10', // get all clients with a balance less than 10
'per_page' => 10, // return 10 results per page
'page' => 2, // paginate to page 2
'include' => 'documents', // include the documents relationship
]);
- lang: curl - lang: curl
label: curl label: curl
source: | source: |
@ -12756,64 +12761,146 @@ paths:
- $ref: "#/components/parameters/updated_at" - $ref: "#/components/parameters/updated_at"
- $ref: "#/components/parameters/is_deleted" - $ref: "#/components/parameters/is_deleted"
- $ref: "#/components/parameters/filter_deleted_clients" - $ref: "#/components/parameters/filter_deleted_clients"
- $ref: "#/components/parameters/vendor_id"
- name: name - name: name
in: query in: query
description: Filter by client name description: |
Filter by client name
```html
?name=bob
```
required: false required: false
schema: schema:
type: string type: string
example: bob example: bob
- name: balance - name: balance
in: query in: query
description: Filter by client balance, format uses an operator and value separated by a colon. lt,lte, gt, gte, eq description: |
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
required: false required: false
schema: schema:
type: string type: string
example: lt:10 example: lt:10
- name: between_balance - name: between_balance
in: query in: query
description: Filter between client balances, format uses two values separated by a colon description: |
Filter between client balances, format uses two values separated by a colon
```html
?between_balance=10:100
```
required: false required: false
schema: schema:
type: string type: string
example: 10:100 example: 10:100
- name: email - name: email
in: query in: query
description: Filter by client email description: |
Filter by client email
```html
?email=bob@gmail.com
```
required: false required: false
schema: schema:
type: string type: string
example: bob@gmail.com example: bob@gmail.com
- name: id_number - name: id_number
in: query in: query
description: Filter by client id_number description: |
Filter by client id_number
```html
?id_number=0001
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: number - name: number
in: query in: query
description: Filter by client number description: |
Filter by client number
```html
?number=0002
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: filter - name: filter
in: query in: query
description: Filters clients on columns - name, id_number, contact.first_name contact.last_name, contact.email, custom_value1-4 description: |
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
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: sort - name: sort
in: query in: query
description: Returns the list sorted by column in ascending or descending order. description: |
Returns the list sorted by column in ascending or descending order.
Ensure you use column | direction, ie.
```html
?sort=id|desc
```
required: false required: false
schema: schema:
type: string type: string
example: id|desc name|desc balance|asc example: id|desc name|desc balance|asc
- name: group
in: query
description: |
Returns the list of clients assigned to {group_id}
```html
?group=X89sjd8
```
required: false
schema:
type: string
example: X89sjd8
- name: client_id
in: query
description: |
Returns the list of clients with {client_id} - proxy call to retrieve a client_id wrapped in an array
```html
?client_id=X89sjd8
```
required: false
schema:
type: string
example: X89sjd8
responses: responses:
200: 200:
description: 'A list of clients' description: 'A list of clients'
@ -12845,12 +12932,58 @@ paths:
description: | description: |
Adds a client to a company Adds a client to a company
> 🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->create([
'name' => 'Client Name',
'contacts' => [
[
'first_name' => 'John',
'last_name' => 'Smith',
'email' => 'john@example.com',
'phone' => '555-0123'
]
],
'address1' => '123 Main St',
'city' => 'New York',
'state' => 'NY',
'postal_code' => '10001',
'country_id' => '1'
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"name": "Client Name",
"contacts": [
{
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com",
"phone": "555-0123"
}
],
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country_id": "1"
}'
operationId: storeClient operationId: storeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: Client object that needs to be added to the company description: Client object that needs to be added to the company
@ -12889,10 +13022,24 @@ paths:
- clients - clients
summary: 'Show client' summary: 'Show client'
description: 'Displays a client by id' description: 'Displays a client by id'
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->show('clientId123');
- lang: curl
label: php
source: |
curl -X GET https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: showClient operationId: showClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -12930,11 +13077,50 @@ paths:
tags: tags:
- clients - clients
summary: 'Update client' summary: 'Update client'
description: 'Handles the updating of a client by id' description: |
Handles the updating of a client by id
> 🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->update('clientId123', [
'name' => 'Updated Name',
'contacts' => [
[
'first_name' => 'John',
'last_name' => 'Smith',
'email' => 'john@example.com'
]
]
]);
- lang: curl
label: curl
source: |
curl -X PUT https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"name": "Updated Name",
"contacts": [
{
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
}
]
}'
operationId: updateClient operationId: updateClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -12979,11 +13165,32 @@ paths:
tags: tags:
- clients - clients
summary: 'Delete client' summary: 'Delete client'
description: 'Handles the deletion of a client by id' description: |
Handles the deletion of a client by id
> ❗ Note
Deleting a client does not purge the client from the system. The delete action will remove the clients data from all
views in the application but keep it all on file. A Client can be laterrestored reversing this action. To permanently wipe a client and
all of their records from the system, use the /purge route
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->delete('clientId123');
- lang: curl
label: curl
source: |
curl -X DELETE https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: deleteClient operationId: deleteClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -13023,7 +13230,8 @@ paths:
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -13066,6 +13274,7 @@ paths:
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
responses: responses:
200: 200:
@ -13132,12 +13341,33 @@ paths:
- custom_value2 - custom_value2
- custom_value3 - custom_value3
- custom_value4 - custom_value4
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->bulk([
'action' => 'archive',
'ids' => ['clientId1', 'clientId2']
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/bulk \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"action": "archive",
"ids": ["clientId1", "clientId2"]
}'
operationId: bulkClients operationId: bulkClients
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: 'Bulk action array' description: 'Bulk action array'
required: true required: true
@ -13176,10 +13406,26 @@ paths:
- clients - clients
summary: 'Add client document' summary: 'Add client document'
description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST' description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST'
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->upload('clientId123', '/path/to/document.pdf');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/clientId123/upload \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest" \
-F "_method=POST" \
-F "documents[]=@/path/to/document.pdf"
operationId: uploadClient operationId: uploadClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -13199,10 +13445,24 @@ paths:
_method: _method:
type: string type: string
example: POST example: POST
documents: documents[]:
type: array type: array
description: |
Array of files to upload. The files should be sent with the key name 'documents[]'.
Supported file types:
- PDF (.pdf)
- Word (.doc, .docx)
- Excel (.xls, .xlsx)
- Images (.jpg, .jpeg, .png)
- Text (.txt)
Maximum file size: 20MB per file
items: items:
type: string
format: binary format: binary
description: The file contents
example: "@/path/to/document.pdf"
responses: responses:
200: 200:
description: 'Returns the client object' description: 'Returns the client object'
@ -13235,15 +13495,28 @@ paths:
description: | description: |
Handles purging a client. Handles purging a client.
Please note this is a destructive action. > ❗ Note
This is a destructive action.
This action will remove all data associated with the client and cannot be undone. This action will remove all data associated with the client and cannot be undone.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->purge('clientId123');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/clientId123/purge \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest" \
-H "X-API-PASSWORD: YOUR-PASSWORD"
operationId: purgeClient operationId: purgeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/X-API-PASSWORD' - $ref: '#/components/parameters/X-API-PASSWORD'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -13283,12 +13556,30 @@ paths:
The id parameter is the client that will be the primary client after the merge has completed. The id parameter is the client that will be the primary client after the merge has completed.
The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client.
> 🚨 **Important**
This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->merge('primaryClientId', 'mergeableClientId');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/primaryClientId/mergeableClientId/merge \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: mergeClient operationId: mergeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/client_include'
- $ref: '#/components/parameters/X-API-PASSWORD' - $ref: '#/components/parameters/X-API-PASSWORD'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -13332,10 +13623,37 @@ paths:
summary: 'Client statement PDF' summary: 'Client statement PDF'
description: 'Return a PDF of the client statement' description: 'Return a PDF of the client statement'
operationId: clientStatement operationId: clientStatement
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$statement = $ninja->clients->statement([
'client_id' => 'clientId123',
'start_date' => '2024-01-01',
'end_date' => '2024-12-31',
'show_payments_table' => true,
'show_aging_table' => true
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/client_statement \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"client_id": "clientId123",
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"show_payments_table": true,
"show_aging_table": true
}'
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: 'Statement Options' description: 'Statement Options'
required: true required: true
@ -13398,7 +13716,8 @@ paths:
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: bounce_id - name: bounce_id
in: path in: path
description: 'The postmark Bounce ID reference' description: 'The postmark Bounce ID reference'
@ -13441,7 +13760,8 @@ paths:
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: client - name: client
in: path in: path
description: 'The Client Hashed ID reference' description: 'The Client Hashed ID reference'
@ -14705,7 +15025,21 @@ components:
client_include: client_include:
name: include name: include
in: query in: query
description: Include child relationships of the Client Object. description: |
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]
```
required: false required: false
schema: schema:
type: string type: string
@ -14858,7 +15192,24 @@ components:
index: index:
name: index name: index
in: query in: query
description: 'Replaces the default response index from data to a user specific string' description: |
Replaces the default response index from data to a user specific string
ie.
```html
?index=new_index
```
response is wrapped
```json
{
'new_index' : [
.....
]
}
```
required: false required: false
schema: schema:
type: string type: string
@ -14881,6 +15232,11 @@ components:
- active - active
- archived - archived
- deleted - deleted
```html
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
```
required: false required: false
schema: schema:
type: string type: string
@ -14890,6 +15246,11 @@ components:
in: query in: query
description: | description: |
Filters the entity list by client_id. Suitable when you only want the entities of a specific client. Filters the entity list by client_id. Suitable when you only want the entities of a specific client.
```html
GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
```
required: false required: false
schema: schema:
type: string type: string
@ -14899,6 +15260,11 @@ components:
in: query in: query
description: | description: |
Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp 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
```
required: false required: false
schema: schema:
type: integer type: integer
@ -14908,6 +15274,11 @@ components:
in: query in: query
description: | description: |
Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp 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
```
required: false required: false
schema: schema:
type: integer type: integer
@ -14917,6 +15288,11 @@ components:
in: query in: query
description: | description: |
Filters the entity list by entities that have been deleted. Filters the entity list by entities that have been deleted.
```html
GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
```
required: false required: false
schema: schema:
type: boolean type: boolean
@ -14926,6 +15302,11 @@ components:
in: query in: query
description: | description: |
Filters the entity list by an associated vendor Filters the entity list by an associated vendor
```html
GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
```
required: false required: false
schema: schema:
type: string type: string
@ -14935,12 +15316,16 @@ components:
in: query in: query
description: | description: |
Filters the entity list and only returns entities for clients that have not been deleted 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
```
required: false required: false
schema: schema:
type: string type: string
example: ?filter_deleted_clients=true example: ?filter_deleted_clients=true
########################### Generic filters available across all filter ################################## ########################### Generic filters available across all filter ##################################
schemas: schemas:
CreditPaymentable: CreditPaymentable:
properties: properties:
@ -20071,11 +20456,11 @@ components:
name: name:
description: 'The name of the client company or organization' description: 'The name of the client company or organization'
type: string type: string
example: "Jim's Housekeeping" example: "Bob & Co Housekeeping"
website: website:
description: 'The website URL of the client company or organization' description: 'The website URL of the client company or organization'
type: string type: string
example: 'https://www.jims-housekeeping.com' example: 'https://www.boandco-housekeeping.com'
private_notes: private_notes:
description: 'Notes that are only visible to the user who created the client' description: 'Notes that are only visible to the user who created the client'
type: string type: string
@ -20113,7 +20498,10 @@ components:
type: string type: string
example: '555-3434-3434' example: '555-3434-3434'
country_id: country_id:
description: "The unique identifier of the client's country" description: |
The unique identifier of the client's country expressed by the countries ISO number.
Optionally, instead of the country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the country_code property.
type: number type: number
format: integer format: integer
example: '1' example: '1'
@ -20165,7 +20553,10 @@ components:
type: string type: string
example: '6110' example: '6110'
shipping_country_id: shipping_country_id:
description: "The unique identifier of the country for the client's shipping address" description: |
The unique identifier of the client's shipping country expressed by the countries ISO number.
Optionally, instead of the shipping_country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the shipping_country_code property.
type: number type: number
format: integer format: integer
example: '4' example: '4'
@ -22203,11 +22594,31 @@ tags:
```html ```html
/api/v1/login?include=company,user /api/v1/login?include=company,user
``` ```
- name: clients - name: clients
x-displayName: Clients x-displayName: Clients
description: |
# description: | The Clients API provides endpoints for managing client records within your company. A client represents a customer
# Endpoint definitions for interacting with clients. or business entity that you provide services or products to.
## Key Features
- Create, read, update, and delete client records
- Manage client contact information and billing details
- View client-specific transaction history
- Handle multiple contacts per client
- Track client-specific settings and preferences
## Client Statuses
- Active: Client is currently active and can be billed
- Archived: Client is archived and hidden from active lists
- Deleted: Client is marked for deletion but retained in the database
## Best Practices
- Always validate client email addresses
- Use unique client numbers for easy reference
- Keep contact information up to date
- Set appropriate client-specific currency and tax settings
- name: products - name: products
x-displayName: Products x-displayName: Products
description: | description: |
@ -22247,7 +22658,7 @@ tags:
Endpoint definitions for interacting with payments. Endpoint definitions for interacting with payments.
- name: quotes - name: quotes
x-displayName:: Quotes x-displayName: Quotes
description: | description: |
Endpoint definitions for interacting with quotes. Endpoint definitions for interacting with quotes.
@ -22295,9 +22706,18 @@ tags:
x-displayName: Reports x-displayName: Reports
description: | description: |
Endpoint definitions for interacting with reports. Endpoint definitions for interacting with reports.
externalDocs: externalDocs:
description: "https://invoiceninja.github.io" description: "Client Libraries"
url: "https://invoiceninja.github.io" x-libraries:
- name: PHP SDK
description: Official PHP client library
url: https://github.com/invoiceninja/sdk-php
packageUrl: https://packagist.org/packages/invoiceninja/sdk-php
language: PHP
- name: User Guide
description: Official user guide
url: https://invoiceninja.github.io
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []

35
openapi/components/parameters.yaml
View File

@ -51,7 +51,21 @@
client_include: client_include:
name: include name: include
in: query in: query
description: Include child relationships of the Client Object. description: |
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]
```
required: false required: false
schema: schema:
type: string type: string
@ -204,7 +218,24 @@
index: index:
name: index name: index
in: query in: query
description: 'Replaces the default response index from data to a user specific string' description: |
Replaces the default response index from data to a user specific string
ie.
```html
?index=new_index
```
response is wrapped
```json
{
'new_index' : [
.....
]
}
```
required: false required: false
schema: schema:
type: string type: string

37
openapi/components/parameters/default_filters.yaml
View File

@ -7,6 +7,11 @@
- active - active
- archived - archived
- deleted - deleted
```html
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
```
required: false required: false
schema: schema:
type: string type: string
@ -16,6 +21,11 @@
in: query in: query
description: | description: |
Filters the entity list by client_id. Suitable when you only want the entities of a specific client. Filters the entity list by client_id. Suitable when you only want the entities of a specific client.
```html
GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
```
required: false required: false
schema: schema:
type: string type: string
@ -25,6 +35,11 @@
in: query in: query
description: | description: |
Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp 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
```
required: false required: false
schema: schema:
type: integer type: integer
@ -34,6 +49,11 @@
in: query in: query
description: | description: |
Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp 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
```
required: false required: false
schema: schema:
type: integer type: integer
@ -43,6 +63,11 @@
in: query in: query
description: | description: |
Filters the entity list by entities that have been deleted. Filters the entity list by entities that have been deleted.
```html
GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
```
required: false required: false
schema: schema:
type: boolean type: boolean
@ -52,6 +77,11 @@
in: query in: query
description: | description: |
Filters the entity list by an associated vendor Filters the entity list by an associated vendor
```html
GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
```
required: false required: false
schema: schema:
type: string type: string
@ -61,8 +91,13 @@
in: query in: query
description: | description: |
Filters the entity list and only returns entities for clients that have not been deleted 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
```
required: false required: false
schema: schema:
type: string type: string
example: ?filter_deleted_clients=true example: ?filter_deleted_clients=true
########################### Generic filters available across all filter ################################## ########################### Generic filters available across all filter ##################################

14
openapi/components/schemas/client_request.yaml
View File

@ -16,11 +16,11 @@
name: name:
description: 'The name of the client company or organization' description: 'The name of the client company or organization'
type: string type: string
example: "Jim's Housekeeping" example: "Bob & Co Housekeeping"
website: website:
description: 'The website URL of the client company or organization' description: 'The website URL of the client company or organization'
type: string type: string
example: 'https://www.jims-housekeeping.com' example: 'https://www.boandco-housekeeping.com'
private_notes: private_notes:
description: 'Notes that are only visible to the user who created the client' description: 'Notes that are only visible to the user who created the client'
type: string type: string
@ -58,7 +58,10 @@
type: string type: string
example: '555-3434-3434' example: '555-3434-3434'
country_id: country_id:
description: "The unique identifier of the client's country" description: |
The unique identifier of the client's country expressed by the countries ISO number.
Optionally, instead of the country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the country_code property.
type: number type: number
format: integer format: integer
example: '1' example: '1'
@ -110,7 +113,10 @@
type: string type: string
example: '6110' example: '6110'
shipping_country_id: shipping_country_id:
description: "The unique identifier of the country for the client's shipping address" description: |
The unique identifier of the client's shipping country expressed by the countries ISO number.
Optionally, instead of the shipping_country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the shipping_country_code property.
type: number type: number
format: integer format: integer
example: '4' example: '4'

43
openapi/misc/misc.yaml
View File

@ -12,11 +12,31 @@ tags:
```html ```html
/api/v1/login?include=company,user /api/v1/login?include=company,user
``` ```
- name: clients - name: clients
x-displayName: Clients x-displayName: Clients
description: |
# description: | The Clients API provides endpoints for managing client records within your company. A client represents a customer
# Endpoint definitions for interacting with clients. or business entity that you provide services or products to.
## Key Features
- Create, read, update, and delete client records
- Manage client contact information and billing details
- View client-specific transaction history
- Handle multiple contacts per client
- Track client-specific settings and preferences
## Client Statuses
- Active: Client is currently active and can be billed
- Archived: Client is archived and hidden from active lists
- Deleted: Client is marked for deletion but retained in the database
## Best Practices
- Always validate client email addresses
- Use unique client numbers for easy reference
- Keep contact information up to date
- Set appropriate client-specific currency and tax settings
- name: products - name: products
x-displayName: Products x-displayName: Products
description: | description: |
@ -56,7 +76,7 @@ tags:
Endpoint definitions for interacting with payments. Endpoint definitions for interacting with payments.
- name: quotes - name: quotes
x-displayName:: Quotes x-displayName: Quotes
description: | description: |
Endpoint definitions for interacting with quotes. Endpoint definitions for interacting with quotes.
@ -104,9 +124,18 @@ tags:
x-displayName: Reports x-displayName: Reports
description: | description: |
Endpoint definitions for interacting with reports. Endpoint definitions for interacting with reports.
externalDocs: externalDocs:
description: "https://invoiceninja.github.io" description: "Client Libraries"
url: "https://invoiceninja.github.io" x-libraries:
- name: PHP SDK
description: Official PHP client library
url: https://github.com/invoiceninja/sdk-php
packageUrl: https://packagist.org/packages/invoiceninja/sdk-php
language: PHP
- name: User Guide
description: Official user guide
url: https://invoiceninja.github.io
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []

2
openapi/paths.yaml
View File

@ -96,7 +96,7 @@ paths:
label: curl label: curl
source: | source: |
curl --request POST \ curl --request POST \
--url 'https://invoicing.co/api/v1/login?include=company,token' \ --url 'https://demo.invoiceninja.com/api/v1/login?include=company,token' \
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'X-Requested-With: XMLHttpRequest' \ --header 'X-Requested-With: XMLHttpRequest' \
--header 'Accept: application/json' --header 'Accept: application/json'

366
openapi/paths/clients.yaml
View File

@ -8,7 +8,12 @@
label: php label: php
source: | source: |
$ninja = new InvoiceNinja("your_token"); $ninja = new InvoiceNinja("your_token");
$invoices = $ninja->clients->all(); $invoices = $ninja->clients->all([
'balance' => 'lt:10', // get all clients with a balance less than 10
'per_page' => 10, // return 10 results per page
'page' => 2, // paginate to page 2
'include' => 'documents', // include the documents relationship
]);
- lang: curl - lang: curl
label: curl label: curl
source: | source: |
@ -60,64 +65,146 @@
- $ref: "#/components/parameters/updated_at" - $ref: "#/components/parameters/updated_at"
- $ref: "#/components/parameters/is_deleted" - $ref: "#/components/parameters/is_deleted"
- $ref: "#/components/parameters/filter_deleted_clients" - $ref: "#/components/parameters/filter_deleted_clients"
- $ref: "#/components/parameters/vendor_id"
- name: name - name: name
in: query in: query
description: Filter by client name description: |
Filter by client name
```html
?name=bob
```
required: false required: false
schema: schema:
type: string type: string
example: bob example: bob
- name: balance - name: balance
in: query in: query
description: Filter by client balance, format uses an operator and value separated by a colon. lt,lte, gt, gte, eq description: |
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
required: false required: false
schema: schema:
type: string type: string
example: lt:10 example: lt:10
- name: between_balance - name: between_balance
in: query in: query
description: Filter between client balances, format uses two values separated by a colon description: |
Filter between client balances, format uses two values separated by a colon
```html
?between_balance=10:100
```
required: false required: false
schema: schema:
type: string type: string
example: 10:100 example: 10:100
- name: email - name: email
in: query in: query
description: Filter by client email description: |
Filter by client email
```html
?email=bob@gmail.com
```
required: false required: false
schema: schema:
type: string type: string
example: bob@gmail.com example: bob@gmail.com
- name: id_number - name: id_number
in: query in: query
description: Filter by client id_number description: |
Filter by client id_number
```html
?id_number=0001
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: number - name: number
in: query in: query
description: Filter by client number description: |
Filter by client number
```html
?number=0002
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: filter - name: filter
in: query in: query
description: Filters clients on columns - name, id_number, contact.first_name contact.last_name, contact.email, custom_value1-4 description: |
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
```
required: false required: false
schema: schema:
type: string type: string
example: a1039883 example: a1039883
- name: sort - name: sort
in: query in: query
description: Returns the list sorted by column in ascending or descending order. description: |
Returns the list sorted by column in ascending or descending order.
Ensure you use column | direction, ie.
```html
?sort=id|desc
```
required: false required: false
schema: schema:
type: string type: string
example: id|desc name|desc balance|asc example: id|desc name|desc balance|asc
- name: group
in: query
description: |
Returns the list of clients assigned to {group_id}
```html
?group=X89sjd8
```
required: false
schema:
type: string
example: X89sjd8
- name: client_id
in: query
description: |
Returns the list of clients with {client_id} - proxy call to retrieve a client_id wrapped in an array
```html
?client_id=X89sjd8
```
required: false
schema:
type: string
example: X89sjd8
responses: responses:
200: 200:
description: 'A list of clients' description: 'A list of clients'
@ -149,12 +236,58 @@
description: | description: |
Adds a client to a company Adds a client to a company
> 🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->create([
'name' => 'Client Name',
'contacts' => [
[
'first_name' => 'John',
'last_name' => 'Smith',
'email' => 'john@example.com',
'phone' => '555-0123'
]
],
'address1' => '123 Main St',
'city' => 'New York',
'state' => 'NY',
'postal_code' => '10001',
'country_id' => '1'
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"name": "Client Name",
"contacts": [
{
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com",
"phone": "555-0123"
}
],
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country_id": "1"
}'
operationId: storeClient operationId: storeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: Client object that needs to be added to the company description: Client object that needs to be added to the company
@ -193,10 +326,24 @@
- clients - clients
summary: 'Show client' summary: 'Show client'
description: 'Displays a client by id' description: 'Displays a client by id'
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->show('clientId123');
- lang: curl
label: php
source: |
curl -X GET https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: showClient operationId: showClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -234,11 +381,50 @@
tags: tags:
- clients - clients
summary: 'Update client' summary: 'Update client'
description: 'Handles the updating of a client by id' description: |
Handles the updating of a client by id
> 🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->update('clientId123', [
'name' => 'Updated Name',
'contacts' => [
[
'first_name' => 'John',
'last_name' => 'Smith',
'email' => 'john@example.com'
]
]
]);
- lang: curl
label: curl
source: |
curl -X PUT https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"name": "Updated Name",
"contacts": [
{
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
}
]
}'
operationId: updateClient operationId: updateClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -283,11 +469,32 @@
tags: tags:
- clients - clients
summary: 'Delete client' summary: 'Delete client'
description: 'Handles the deletion of a client by id' description: |
Handles the deletion of a client by id
> ❗ Note
Deleting a client does not purge the client from the system. The delete action will remove the clients data from all
views in the application but keep it all on file. A Client can be laterrestored reversing this action. To permanently wipe a client and
all of their records from the system, use the /purge route
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->delete('clientId123');
- lang: curl
label: curl
source: |
curl -X DELETE https://demo.invoiceninja.com/api/v1/clients/clientId123 \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: deleteClient operationId: deleteClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -327,7 +534,8 @@
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -370,6 +578,7 @@
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
responses: responses:
200: 200:
@ -436,12 +645,33 @@
- custom_value2 - custom_value2
- custom_value3 - custom_value3
- custom_value4 - custom_value4
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->bulk([
'action' => 'archive',
'ids' => ['clientId1', 'clientId2']
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/bulk \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"action": "archive",
"ids": ["clientId1", "clientId2"]
}'
operationId: bulkClients operationId: bulkClients
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: 'Bulk action array' description: 'Bulk action array'
required: true required: true
@ -480,10 +710,26 @@
- clients - clients
summary: 'Add client document' summary: 'Add client document'
description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST' description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST'
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->upload('clientId123', '/path/to/document.pdf');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/clientId123/upload \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest" \
-F "_method=POST" \
-F "documents[]=@/path/to/document.pdf"
operationId: uploadClient operationId: uploadClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -503,10 +749,24 @@
_method: _method:
type: string type: string
example: POST example: POST
documents: documents[]:
type: array type: array
description: |
Array of files to upload. The files should be sent with the key name 'documents[]'.
Supported file types:
- PDF (.pdf)
- Word (.doc, .docx)
- Excel (.xls, .xlsx)
- Images (.jpg, .jpeg, .png)
- Text (.txt)
Maximum file size: 20MB per file
items: items:
type: string
format: binary format: binary
description: The file contents
example: "@/path/to/document.pdf"
responses: responses:
200: 200:
description: 'Returns the client object' description: 'Returns the client object'
@ -539,15 +799,28 @@
description: | description: |
Handles purging a client. Handles purging a client.
Please note this is a destructive action. > ❗ Note
This is a destructive action.
This action will remove all data associated with the client and cannot be undone. This action will remove all data associated with the client and cannot be undone.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->purge('clientId123');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/clientId123/purge \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest" \
-H "X-API-PASSWORD: YOUR-PASSWORD"
operationId: purgeClient operationId: purgeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/X-API-PASSWORD' - $ref: '#/components/parameters/X-API-PASSWORD'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -587,12 +860,30 @@
The id parameter is the client that will be the primary client after the merge has completed. The id parameter is the client that will be the primary client after the merge has completed.
The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client.
> 🚨 **Important**
This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->merge('primaryClientId', 'mergeableClientId');
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/clients/primaryClientId/mergeableClientId/merge \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "X-Requested-With: XMLHttpRequest"
operationId: mergeClient operationId: mergeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/client_include'
- $ref: '#/components/parameters/X-API-PASSWORD' - $ref: '#/components/parameters/X-API-PASSWORD'
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'
@ -636,10 +927,37 @@
summary: 'Client statement PDF' summary: 'Client statement PDF'
description: 'Return a PDF of the client statement' description: 'Return a PDF of the client statement'
operationId: clientStatement operationId: clientStatement
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("YOUR-TOKEN");
$statement = $ninja->clients->statement([
'client_id' => 'clientId123',
'start_date' => '2024-01-01',
'end_date' => '2024-12-31',
'show_payments_table' => true,
'show_aging_table' => true
]);
- lang: curl
label: curl
source: |
curl -X POST https://demo.invoiceninja.com/api/v1/client_statement \
-H "X-API-TOKEN: YOUR-TOKEN" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"client_id": "clientId123",
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"show_payments_table": true,
"show_aging_table": true
}'
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: 'Statement Options' description: 'Statement Options'
required: true required: true
@ -702,7 +1020,8 @@
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: bounce_id - name: bounce_id
in: path in: path
description: 'The postmark Bounce ID reference' description: 'The postmark Bounce ID reference'
@ -745,7 +1064,8 @@
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/include' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include'
- name: client - name: client
in: path in: path
description: 'The Client Hashed ID reference' description: 'The Client Hashed ID reference'