INinvoiceninja
clients

List clients

Changed on

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.

get/api/v1/clients

Request

Query parameters

includestring

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
indexstring
Example:user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_pageinteger
Example:20

The number of records to return for each request, default is 20

pageinteger
Example:1

The page number to return for this request (when performing pagination), default is 1

sortstring[]

Order the list by choosing a column and direction. Each value uses the form column|asc or column|desc.

Single sort — pass one argument, for example sort=id|desc.

Multiple sorts — chain ordering with repeated sort[] keys. The first is the main sort, the next breaks ties, and so on, for example
sort[]=id|desc&sort[]=number|asc.

For clients, the API honors clients columns (such as name, balance, number), natural ordering for number, plus contacts, contact_email, and name / display_name (display name is normalized to name). Values that are not supported are ignored.

[
  "name|desc",
  "balance|asc"
]
statusstring

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
created_atinteger

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_atinteger

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deletedboolean

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clientsstring

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
namestring

Filter by client name

?name=bob
balancestring

Filter by client balance, format uses an operator and value separated by a colon. lt,lte, gt, gte, eq

?balance=lt:10

ie all clients whose balance is less than 10

between_balancestring

Filter between client balances, format uses two values separated by a colon

?between_balance=10:100
emailstring

Filter by client email

?email=jane.doe@acme.com
id_numberstring

Filter by client id_number

?id_number=ACME-0001
numberstring

Filter by client number

?number=0002
filterstring

Broad filter which targets multiple client columns:

  name, 
  id_number, 
  contact.first_name 
  contact.last_name, 
  contact.email, 
  contact.phone
  custom_value1,
  custom_value2,
  custom_value3,
  custom_value4,

?filter=Bobby
groupstring

Returns the list of clients assigned to {group_id}

  ?group=Wpmbk5ezJn
client_idstring

Returns the list of clients with {client_id} - proxy call to retrieve a client_id wrapped in an array

  ?client_id=Opnel5aKBz

Headers

X-API-TOKENstring required
Example:TOKEN

The API token to be used for authentication

X-Requested-Withstring required
Example:XMLHttpRequest

Used to send the XMLHttpRequest header

Response

A list of clients

Example response

{
  "data": [
    {
      "id": "Opnel5aKBz",
      "contacts": [
        {
          "id": "Opnel5aKBz",
          "user_id": "Opnel5aKBz",
          "client_id": "Opnel5aKBz",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "555-152-4524",
          "accepted_terms_version": "A long set of ToS",
          "password": "*****",
          "confirmation_code": "333-sdjkh34gbasd",
          "token": "333-sdjkh34gbasd",
          "contact_key": "JD0X52bkfZlJRiroCJ0tcSiAjsJTntZ5uqKdiZ0a",
          "is_primary": true,
          "confirmed": true,
          "is_locked": true,
          "send_email": true,
          "failed_logins": 3,
          "email_verified_at": 134341234234,
          "last_login": 134341234234,
          "created_at": 134341234234,
          "updated_at": 134341234234,
          "deleted_at": 134341234234
        }
      ],
      "user_id": "Ua6Rw4pVbS",
      "assigned_user_id": "Ua6Rw4pVbS",
      "name": "Jim's Housekeeping",
      "website": "https://www.jims-housekeeping.com",
      "private_notes": "Client prefers email communication over phone calls",
      "client_hash": "asdfkjhk342hjhbfdvmnfb1",
      "industry_id": 5,
      "size_id": 2,
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "Beverly Hills",
      "state": "California",
      "postal_code": "90210",
      "phone": "555-3434-3434",
      "custom_value1": "Preferred contact: Email",
      "custom_value2": "Account manager: John Doe",
      "custom_value3": "VIP client: Yes",
      "custom_value4": "Annual contract value: $50,000",
      "vat_number": "VAT123456",
      "number": "CL-0001",
      "shipping_address1": "5 Wallaby Way",
      "shipping_address2": "Suite 5",
      "shipping_city": "Perth",
      "shipping_state": "Western Australia",
      "shipping_postal_code": "6110",
      "shipping_country_id": 4,
      "balance": 500,
      "paid_to_date": 2000,
      "credit_balance": 100,
      "last_login": 1628686031,
      "created_at": 1617629031,
      "updated_at": 1628445631,
      "group_settings_id": "Opnel5aKBz",
      "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
      "payment_balance": 100,
      "settings": {
        "currency_id": "1",
        "timezone_id": "15",
        "date_format_id": "15",
        "military_time": true,
        "language_id": "1",
        "show_currency_code": true,
        "payment_terms": 1,
        "company_gateway_ids": "1,2,3,4",
        "custom_value1": "Custom Label",
        "custom_value2": "Custom Label",
        "custom_value3": "Custom Label",
        "custom_value4": "Custom Label",
        "default_task_rate": 10,
        "send_reminders": true,
        "enable_client_portal_tasks": true,
        "email_style": "light",
        "reply_to_email": "email@gmail.com",
        "bcc_email": "email@gmail.com, contact@gmail.com",
        "pdf_email_attachment": true,
        "ubl_email_attachment": true,
        "email_style_custom": "<HTML></HTML>",
        "counter_number_applied": "when_sent",
        "quote_number_applied": "when_sent",
        "custom_message_dashboard": "Please pay invoices immediately",
        "custom_message_unpaid_invoice": "Please pay invoices immediately",
        "custom_message_paid_invoice": "Thanks for paying this invoice!",
        "custom_message_unapproved_quote": "Please approve quote",
        "lock_invoices": true,
        "auto_archive_invoice": true,
        "auto_archive_quote": true,
        "auto_convert_quote": true,
        "inclusive_taxes": true,
        "task_number_pattern": "{$year}-{$counter}",
        "task_number_counter": 1,
        "reminder_send_time": 32400,
        "expense_number_pattern": "{$year}-{$counter}",
        "expense_number_counter": 1,
        "vendor_number_pattern": "{$year}-{$counter}",
        "vendor_number_counter": 1,
        "ticket_number_pattern": "{$year}-{$counter}",
        "ticket_number_counter": 1,
        "payment_number_pattern": "{$year}-{$counter}",
        "payment_number_counter": 1,
        "invoice_number_pattern": "{$year}-{$counter}",
        "invoice_number_counter": 1,
        "quote_number_pattern": "{$year}-{$counter}",
        "quote_number_counter": 1,
        "client_number_pattern": "{$year}-{$counter}",
        "client_number_counter": 1,
        "credit_number_pattern": "{$year}-{$counter}",
        "credit_number_counter": 1,
        "recurring_invoice_number_prefix": "R",
        "reset_counter_frequency_id": 1,
        "reset_counter_date": "2019-01-01",
        "counter_padding": 1,
        "shared_invoice_quote_counter": true,
        "update_products": true,
        "convert_products": true,
        "fill_products": true,
        "invoice_terms": "Invoice Terms are...",
        "quote_terms": "Quote Terms are...",
        "invoice_taxes": 1,
        "invoice_design_id": "1",
        "quote_design_id": "1",
        "invoice_footer": "1",
        "invoice_labels": "1",
        "tax_rate1": 10,
        "tax_name1": "GST",
        "tax_rate2": 10,
        "tax_name2": "GST",
        "tax_rate3": 10,
        "tax_name3": "GST",
        "payment_type_id": "1",
        "custom_fields": "{}",
        "email_footer": "A default email footer",
        "email_sending_method": "default",
        "gmail_sending_user_id": "F76sd34D",
        "email_subject_invoice": "Your Invoice Subject",
        "email_subject_quote": "Your Quote Subject",
        "email_subject_payment": "Your Payment Subject",
        "email_template_invoice": "<HTML></HTML>",
        "email_template_quote": "<HTML></HTML>",
        "email_template_payment": "<HTML></HTML>",
        "email_subject_reminder1": "<HTML></HTML>",
        "email_subject_reminder2": "<HTML></HTML>",
        "email_subject_reminder3": "<HTML></HTML>",
        "email_subject_reminder_endless": "<HTML></HTML>",
        "email_template_reminder1": "<HTML></HTML>",
        "email_template_reminder2": "<HTML></HTML>",
        "email_template_reminder3": "<HTML></HTML>",
        "email_template_reminder_endless": "<HTML></HTML>",
        "enable_portal_password": true,
        "show_accept_invoice_terms": true,
        "show_accept_quote_terms": true,
        "require_invoice_signature": true,
        "require_quote_signature": true,
        "name": "Acme Co",
        "company_logo": {},
        "website": "https://www.acme.com",
        "address1": "Suite 888",
        "address2": "5 Jimbo Way",
        "city": "Sydney",
        "state": "Florisa",
        "postal_code": "90210",
        "phone": "555-213-3948",
        "email": "joe@acme.co",
        "country_id": "1",
        "vat_number": "32 120 377 720",
        "page_size": "A4",
        "font_size": 9,
        "primary_font": "roboto",
        "secondary_font": "roboto",
        "email_template_statement": "template matter",
        "email_subject_statement": "subject matter",
        "quote_footer": "the quote footer",
        "email_subject_custom1": "Custom Subject 1",
        "email_subject_custom2": "Custom Subject 2",
        "email_subject_custom3": "Custom Subject 3",
        "email_template_custom1": "<HTML>",
        "email_template_custom2": "<HTML>",
        "email_template_custom3": "<HTML>",
        "num_days_reminder1": 9,
        "num_days_reminder2": 9,
        "num_days_reminder3": 9,
        "schedule_reminder1": "after_invoice_date",
        "schedule_reminder2": "after_invoice_date",
        "schedule_reminder3": "after_invoice_date",
        "late_fee_amount1": 10,
        "late_fee_amount2": 20,
        "late_fee_amount3": 100,
        "endless_reminder_frequency_id": "1",
        "default_expense_payment_type_id": "0",
        "e_invoice_type": "EN16931",
        "mailgun_endpoint": "api.mailgun.net or api.eu.mailgun.net",
        "client_initiated_payments_minimum": 10,
        "custom_sending_email": "bob@gmail.com",
        "company_logo_size": 100,
        "email_alignment": "left",
        "postmark_secret": "123456",
        "mailgun_secret": "123456",
        "mailgun_domain": "sandbox123456.mailgun.org",
        "besr_id": "123456",
        "qr_iban": "CH123456",
        "email_subject_purchase_order": "Purchase Order",
        "email_template_purchase_order": "Please see attached your purchase order.",
        "purchase_order_public_notes": "Please see attached your purchase order.",
        "purchase_order_terms": "Please see attached your purchase order.",
        "purchase_order_footer": "Please see attached your purchase order.",
        "purchase_order_design_id": "hd677df",
        "purchase_order_number_pattern": "PO-000000",
        "purchase_order_number_counter": 1,
        "page_numbering_alignment": "left",
        "email_from_name": "Bob Smith",
        "entity_send_time": 9,
        "reply_to_name": "Bob Smith",
        "recurring_invoice_number_pattern": "R-000000",
        "recurring_invoice_number_counter": 1,
        "client_portal_under_payment_minimum": 10,
        "auto_bill_date": "on_send_date",
        "primary_color": "#ffffff",
        "secondary_color": "#ffffff",
        "auto_bill": "off",
        "client_portal_terms": "Please see attached your invoice.",
        "client_portal_privacy_policy": "These are the terms of use for using the client portal.",
        "portal_design_id": "hd677df",
        "late_fee_endless_percent": 10,
        "late_fee_endless_amount": 10,
        "email_signature": "Bob Smith"
      },
      "classification": "VIP",
      "public_notes": "These are public notes visible to clients"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Changes

  • 89876e7e51d6Revision changes
    • info

      for the query request parameter sort, the type was generalized from string to array

  • 69a36036d334Revision changes
    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status