API

Invoice Ninja provides a RESTful API, click here to see the full list of methods available.

To access the API you first need to create a token using the “API Tokens” page under “Advanced Settings”.

Note

Replace ninja.test with https://app.invoiceninja.com to access a hosted account.

Reading Data

Here’s an example of reading the list of clients using cURL from the command line.

curl -X GET ninja.test/api/v1/clients -H "X-Ninja-Token: TOKEN"

For invoices, quotes, tasks and payments simply change the object type.

curl -X GET ninja.test/api/v1/invoices -H "X-Ninja-Token: TOKEN"

You can search clients by their email address or id number and invoices by their invoice number.

curl -X GET ninja.test/api/v1/clients?email=<value> -H "X-Ninja-Token: TOKEN"
curl -X GET ninja.test/api/v1/clients?id_number=<value> -H "X-Ninja-Token: TOKEN"
curl -X GET ninja.test/api/v1/invoices?invoice_number=<value> -H "X-Ninja-Token: TOKEN"

To load a single record specify the Id in the URL.

curl -X GET ninja.test/api/v1/invoices/1 -H "X-Ninja-Token: TOKEN"

You can specify additional relationships to load using the include parameter.

curl -X GET ninja.test/api/v1/clients/1?include=invoices.invitations -H "X-Ninja-Token: TOKEN"

You can download a PDF using the following URL

curl -X GET ninja.test/api/v1/download/1 -H "X-Ninja-Token: TOKEN"

Optional Settings

The following are optional query parameter settings:

  • serializer: Either array (the default) or JSON.
  • include: A comma-separated list of nested relationships to include.
  • client_id: If set the results will be filtered by the client.
  • page: The page number of results to return when the results are paginated.
  • per_page: The number of results to return per page.
  • updated_at: Timestamp used as a filter to only show recently updated records.

Creating Data

Tip

Add -H "X-Requested-With: XMLHttpRequest" to see validation errors in the response.

Here’s an example of creating a client. Note that email address is a property of the client’s contact not the client itself.

curl -X POST ninja.test/api/v1/clients -H "Content-Type:application/json" \
  -d '{"name":"Client","contact":{"email":"test@example.com"}}' -H "X-Ninja-Token: TOKEN"

You can also update a client by specifying a value for ‘id’. Next, here’s an example of creating an invoice.

curl -X POST ninja.test/api/v1/invoices -H "Content-Type:application/json" \
  -d '{"client_id":"1", "invoice_items":[{"product_key": "ITEM", "notes":"Test", "cost":10, "qty":1}]}' \
  -H "X-Ninja-Token: TOKEN"

If the email field is set we’ll search for a matching client, if no matches are found a new client will be created.

If the product_key is set and matches an existing record the product fields will be auto-populated. You can use a comma-separated value to create an invoice with multiple products.

Options

The following options are available when creating an invoice.

  • email_invoice: Email the invoice to the client.
  • email_type: Set to reminder1, reminder2 or reminder3 to use the reminder template.
  • auto_bill: Attempt to auto-bill the invoice using stored payment methods or credits.
  • paid: Create a payment for the defined amount.

Updating Data

Note

When updating a client it’s important to include the contact ids.

curl -X PUT ninja.test/api/v1/clients/1 -H "Content-Type:application/json" \
  -d '{"name":"test", "contacts":[{"id": 1, "first_name": "test"}]}' \
  -H "X-Ninja-Token: TOKEN"

You can archive, delete or restore an entity by setting action in the request

curl -X PUT ninja.test/api/v1/invoices/1?action=archive \
  -H "X-Ninja-Token: TOKEN"

Tip

For invoices use mark_sent to manually mark the invoice as sent

Emailing Invoices

To email an invoice use the email_invoice command passing the id of the invoice.

curl -X POST ninja.test/api/v1/email_invoice -d '{"id":1}' \
  -H "Content-Type:application/json" -H "X-Ninja-Token: TOKEN"