invoiceninja/openapi/paths/clients.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();          
      - 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: |
            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"
        - $ref: "#/components/parameters/vendor_id"
        - name: name
          in: query
          description: Filter by client name
          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
          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
          required: false
          schema:
            type: string
          example: 10:100
        - name: email
          in: query
          description: Filter by client email
          required: false
          schema:
            type: string
          example: bob@gmail.com
        - name: id_number
          in: query
          description: Filter by client id_number
          required: false
          schema:
            type: string
          example: a1039883
        - name: number
          in: query
          description: Filter by client number
          required: false
          schema:
            type: string
          example: a1039883
        - name: filter
          in: query
          description: Filters clients on columns - name, id_number, contact.first_name contact.last_name, contact.email, custom_value1-4
          required: false
          schema:
            type: string
          example: a1039883
        - name: sort
          in: query
          description: Returns the list sorted by column in ascending or descending order.
          required: false
          schema:
            type: string
          example: id|desc name|desc balance|asc 

      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: |
            Adds a client to a company
              
            When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.            

      operationId: storeClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/client_include'
      requestBody:
        description: Client object that needs to be added to the company
        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: 'Displays a client by id'
      operationId: showClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $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: 'Handles the updating of a client by id'
      operationId: updateClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $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: 'Handles the deletion of a client by id'
      operationId: deleteClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $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: 'Displays a client by id, essentially an alias of the show route'
      operationId: editClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/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: 'Returns a blank object with default values'
      operationId: getClientsCreate
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $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: |
        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 the setting of 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        

      operationId: bulkClients
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/index'
      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: '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'
      operationId: uploadClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $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
                  items:
                    format: binary
      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: |
            Handles purging a client.

            Please note this is a destructive action.

            This action will remove all data associated with the client and cannot be undone.            
      operationId: purgeClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/X-API-PASSWORD'
        - $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'
        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: |
            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.            
      operationId: mergeClient
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/client_include'
        - $ref: '#/components/parameters/X-API-PASSWORD'
        - 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: 'Return a PDF of the client statement'
      operationId: clientStatement
      parameters:
        - $ref: '#/components/parameters/X-API-TOKEN'
        - $ref: '#/components/parameters/X-Requested-With'
        - $ref: '#/components/parameters/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: '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/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: '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/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'