1167 lines
38 KiB
YAML
1167 lines
38 KiB
YAML
/api/v1/clients:
|
|
get:
|
|
tags:
|
|
- clients
|
|
summary: |
|
|
List clients
|
|
x-codeSamples:
|
|
- lang: php
|
|
label: php
|
|
source: |
|
|
$ninja = new InvoiceNinja("your_token");
|
|
$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
|
|
label: curl
|
|
source: |
|
|
curl --request GET \
|
|
--url 'https://invoicing.co/api/v1/clients?per_page=10&page=1&sort=name&sort_dir=asc' \
|
|
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
|
|
--header 'Accept: application/json'
|
|
description: |
|
|
## 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.
|
|
|
|
operationId: getClients
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: "#/components/parameters/status"
|
|
- $ref: "#/components/parameters/created_at"
|
|
- $ref: "#/components/parameters/updated_at"
|
|
- $ref: "#/components/parameters/is_deleted"
|
|
- $ref: "#/components/parameters/filter_deleted_clients"
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
Filter by client name
|
|
|
|
```html
|
|
?name=bob
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: bob
|
|
- name: balance
|
|
in: query
|
|
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
|
|
schema:
|
|
type: string
|
|
example: lt:10
|
|
- name: between_balance
|
|
in: query
|
|
description: |
|
|
Filter between client balances, format uses two values separated by a colon
|
|
|
|
```html
|
|
?between_balance=10:100
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: 10:100
|
|
- name: email
|
|
in: query
|
|
description: |
|
|
Filter by client email
|
|
|
|
```html
|
|
?email=bob@gmail.com
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: bob@gmail.com
|
|
- name: id_number
|
|
in: query
|
|
description: |
|
|
Filter by client id_number
|
|
|
|
```html
|
|
?id_number=0001
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: a1039883
|
|
- name: number
|
|
in: query
|
|
description: |
|
|
Filter by client number
|
|
|
|
```html
|
|
?number=0002
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: a1039883
|
|
- name: filter
|
|
in: query
|
|
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
|
|
schema:
|
|
type: string
|
|
example: a1039883
|
|
- name: sort
|
|
in: query
|
|
description: |
|
|
Returns the list sorted by column in ascending or descending order.
|
|
|
|
Ensure you use column | direction, ie.
|
|
|
|
```html
|
|
?sort=id|desc
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
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:
|
|
200:
|
|
description: 'A list of clients'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Create client'
|
|
description: |
|
|
|
|
## POST /api/v1/clients
|
|
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.
|
|
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",
|
|
"send_email": true
|
|
}
|
|
],
|
|
"address1": "123 Main St",
|
|
"city": "New York",
|
|
"state": "NY",
|
|
"postal_code": "10001",
|
|
"country_id": "1"
|
|
}'
|
|
operationId: storeClient
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClientRequest'
|
|
responses:
|
|
200:
|
|
description: 'Returns the saved client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
'/api/v1/clients/{id}':
|
|
get:
|
|
tags:
|
|
- clients
|
|
summary: 'Show client'
|
|
description: |
|
|
## GET /api/v1/clients/{id}
|
|
|
|
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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
put:
|
|
tags:
|
|
- clients
|
|
summary: 'Update client'
|
|
description: |
|
|
## PUT /api/v1/clients/{id}
|
|
|
|
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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
requestBody:
|
|
description: Client object that needs to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClientRequest'
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
delete:
|
|
tags:
|
|
- clients
|
|
summary: 'Delete client'
|
|
description: |
|
|
## DELETE /api/v1/clients/{id}
|
|
|
|
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 on file in case it needs to be restored.
|
|
|
|
A Client can be later restored reversing this action.
|
|
|
|
To permanently wipe a client and all of their records from the system, use the [/purge route](/#tag/clients/POST/api/v1/clients/{id}/purge)
|
|
|
|
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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns a HTTP status'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
'/api/v1/clients/{id}/edit':
|
|
get:
|
|
tags:
|
|
- clients
|
|
summary: 'Edit Client'
|
|
description: |
|
|
## GET /api/v1/clients/{id}/edit
|
|
Displays a client by id, essentially an alias of the show route
|
|
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: editClient
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
/api/v1/clients/create:
|
|
get:
|
|
tags:
|
|
- clients
|
|
summary: 'Blank Client'
|
|
description: |
|
|
## GET /api/v1/clients/create
|
|
|
|
Returns a blank object with default values
|
|
|
|
x-codeSamples:
|
|
- lang: php
|
|
label: php
|
|
source: |
|
|
$ninja = new InvoiceNinja("YOUR-TOKEN");
|
|
$client = $ninja->clients->model();
|
|
- lang: curl
|
|
label: php
|
|
source: |
|
|
curl -X GET https://demo.invoiceninja.com/api/v1/clients/create \
|
|
-H "X-API-TOKEN: YOUR-TOKEN" \
|
|
-H "X-Requested-With: XMLHttpRequest"
|
|
operationId: getClientsCreate
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
responses:
|
|
200:
|
|
description: 'A blank client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
/api/v1/clients/bulk:
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Bulk client actions'
|
|
description: |
|
|
## POST /api/v1/clients/bulk
|
|
|
|
Bulk actions allow to make changes to multiple clients in a single request the following actions are supported
|
|
|
|
- archive
|
|
- restore
|
|
- delete
|
|
- template _requires template,template_id properties also_
|
|
- assign_group _requires group_settings_id also_
|
|
- bulk_update _requires column,new_value also_
|
|
|
|
All of these actions require an array of client ids to perform the requested action on ie.
|
|
|
|
"ids":['id1','id2']
|
|
|
|
actions such as template, assign_group and bulk_update also require additional properties to be passed in the request
|
|
|
|
- template
|
|
|
|
The template bulk action allows the creation of a custom template using the provided template_id to be run against the array of clients provided.
|
|
|
|
- assign_group
|
|
|
|
Allows setting multiple clients to a single group
|
|
|
|
- bulk_update
|
|
|
|
Allows updating certain columns on the client model in bulk. the current list of supported columns that can be updated archived_at:
|
|
|
|
- public_notes
|
|
- industry_id
|
|
- size_id
|
|
- country_id
|
|
- custom_value1
|
|
- custom_value2
|
|
- custom_value3
|
|
- 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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
requestBody:
|
|
description: 'Bulk action array'
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GenericBulkAction'
|
|
|
|
responses:
|
|
200:
|
|
description: 'The Client list Response of the updated clients that were bulk updated'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
'/api/v1/clients/{id}/upload':
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Add client document'
|
|
description: |
|
|
## POST /api/v1/clients/{id}/upload
|
|
|
|
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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
_method:
|
|
type: string
|
|
example: POST
|
|
documents[]:
|
|
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:
|
|
type: string
|
|
format: binary
|
|
description: The file contents
|
|
example: "@/path/to/document.pdf"
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
'/api/v1/clients/{id}/purge':
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Purge client'
|
|
description: |
|
|
## POST /api/v1/clients/{id}/purge
|
|
|
|
Handles purging a client.
|
|
|
|
> ❗ Note
|
|
This is a destructive action.
|
|
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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/X-API-PASSWORD'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
'/api/v1/clients/{id}/{mergeable_client_hashed_id}/merge':
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Merge client'
|
|
description: |
|
|
## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge
|
|
|
|
Handles merging 2 clients
|
|
|
|
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.
|
|
|
|
> 🚨 **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
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/X-API-PASSWORD'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: id
|
|
in: path
|
|
description: 'The Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
- name: mergeable_client_hashed_id
|
|
in: path
|
|
description: 'The Mergeable Client Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
/api/v1/client_statement:
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Client statement PDF'
|
|
description: |
|
|
## POST /api/v1/client_statement
|
|
|
|
Return a PDF of the client statement
|
|
|
|
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:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
requestBody:
|
|
description: 'Statement Options'
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
start_date:
|
|
description: 'The start date of the statement period - format Y-m-d'
|
|
type: string
|
|
end_date:
|
|
description: 'The start date of the statement period - format Y-m-d'
|
|
type: string
|
|
client_id:
|
|
description: 'The hashed ID of the client'
|
|
type: string
|
|
show_payments_table:
|
|
description: 'Flag which determines if the payments table is shown'
|
|
type: boolean
|
|
show_credits_table:
|
|
description: 'Flag which determines if the credits table is shown'
|
|
type: boolean
|
|
show_aging_table:
|
|
description: 'Flag which determines if the aging table is shown'
|
|
type: boolean
|
|
type: object
|
|
responses:
|
|
200:
|
|
description: 'Returns the client object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Client'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
5XX:
|
|
description: 'Server error'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
/api/v1/reactivate_email/{bounce_id}:
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Removes email suppression of a user in the system'
|
|
description: |
|
|
## POST /api/v1/reactivate_email/{bounce_id}
|
|
|
|
Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again.
|
|
|
|
operationId: reactivateEmail
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: bounce_id
|
|
in: path
|
|
description: 'The postmark Bounce ID reference'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: 123243
|
|
responses:
|
|
200:
|
|
description: 'Success'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
400:
|
|
description: 'Postmark exception - generated if the suppression cannot be removed for any reason'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
5XX:
|
|
description: 'Server error'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
/api/v1/clients/{client}/updateTaxData:
|
|
post:
|
|
tags:
|
|
- clients
|
|
summary: 'Update tax data'
|
|
description: |
|
|
## POST /api/v1/clients/{client}/updateTaxData
|
|
|
|
Updates the clients tax data - if their address has changed
|
|
|
|
operationId: updateClientTaxData
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- $ref: '#/components/parameters/client_include'
|
|
- name: client
|
|
in: path
|
|
description: 'The Client Hashed ID reference'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: V2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Success'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
400:
|
|
description: 'Postmark exception - generated if the suppression cannot be removed for any reason'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
5XX:
|
|
description: 'Server error'
|
|
default:
|
|
$ref: '#/components/responses/default' |