IntakeQ Invoice API

Overview

The IntakeQ Invoice API is composed of HTTP endpoints that can be reached through a REST API. Additionally, you can setup webhooks that are fired when an invoice is issued or paid; giving you the opportunity to watch for changes in realtime and integrate with 3rd party software.

For Intake Forms API, please refer to this article.

Getting Started

To get started, you first need to enable API access (navigate to More > Settings > Integrations > Developer API). That’s also where you’ll find your API key, used to authenticate your HTTP calls.

Only the main account owner has access to the API tab.

Never expose your API key in plain text (config files, source control, etc.).

Consider setting an IP Allow-List as explained here.

Base URL

All endpoints are located under the following URL: https://intakeq.com/api/v1/

An example of a typical API call would look like this:

[GET] https://intakeq.com/api/v1/invoices/[invoice-id]

Authentication

Every HTTP request needs to contain your API key embedded in an authentication header named X-Auth-Key.

X-Auth-Key:xxxxxxxxxxxxxxxxxxxxxxxxx

The Invoice Object

Below is the JSON representation of the invoice object, which is used throughout this API.

{
   Id: "123", 
   Number: 123,
   ClientName: "test",
   ClientEmail: "test@email.com",  
   ClientId: "2655259c-f342-4cf9-9534-067247d7ec34", //GUID used internally
   ClientIdNumber: 999,	
   Status: "Paid", // Unpaid, Paid, PastDue
   IssuedDate: 1458526480368, //Unix timestamp,
   DueDate: 1458526484236, //Unix timestamp,
   DateCreated: 1458526484236, //Unix timestamp,
   LastModified: 1458526484236, //Unix timestamp,
   CurrencyIso: "USD",
   DiscountAmount: 30.45,
   DiscountPercent: 0.20, 
   DiscountType: "Percentage", // Percentage, Amount
   SubTotal: 163.50,
   TotalAmount: 163.50,
   AmountDue: 60,
   AmountPaid: 80,
   NoteToClient: "Thank you to choose IntakeQ",
   AllowTipping: true,
   TipAmount: 18,
   Automated: true,
   CreatedBy: "Dr. Test",
   AdditionalEmailRecipients: ["test2@email.com"],
   Payments: [
	{
	   Date: 1458526484236,
           Amount: 80,
           Currency: "USD",
           Method: "CreditCard",
           ProcessedBy: "Dr. Test",
	   ProcessedByType: "Client", // Client, Provider, Automation
           TipAmount: 0,
           RefundedAmount: 0,
           AdditionalInfo: "Split Payment", 
           CardDetails: {
	       Brand" : "VISA",                
               LastDigits" : "1111",
               ExpirationMonth : 7,
               ExpirationYear" : 2022,                
               CardId" : "ccof:xyz"
	   }
	}, 
        {
	   Date: 1581364209,
           Amount: 75,
           Currency: "USD",
           Method: "CreditCard",
           ProcessedBy: "Dr. Test",
	   ProcessedByType: "Client", // Client, Provider, Automation
           TipAmount: 0,
           RefundedAmount: 0,
           AdditionalInfo: "Split Payment", 
           CardDetails: {
	       Brand" : "VISA",                
               LastDigits" : "1111",
               ExpirationMonth : 7,
               ExpirationYear" : 2022,                
               CardId" : "ccof:xyz"
	   }
	}
   ],
   Items: [
	{
 	    "AppointmentId" : "5e3a40492604a910d0883401",           
            "ProductId" : null, 
            "Description" : "Physical Therapy Treatment Session", 
            "TotalTaxAmount" : 0, 
            "Units" : 1, 
            "Price" : 150, 
            "Date" : 1581364209, 
            "Taxes" : [
		{ Name = 'HST', Percentage = 0.13 }
            ], 
            "TaxesIncludedInPrice" : true, 
            "IsCopay" : false, 
            "TotalAmount" : 150.0, 
            "ServiceCode" : "97110", 
	    "SubItems" : [
                {
                    "ServiceCode" : "97110", 
                    "Price" : 37.5,                     
                    "Units" : 1, 
                    "Description" : null, 
                    "Date" : 1581191409, 
                    "Modifiers" : [
                    ]
                }, 
                {
                    "ServiceCode" : "97140", 
                    "Price" : 37.5,                    
                    "Units" : 3, 
                    "Description" : null, 
                    "Date" : null, 
                    "Modifiers" : [
                    ]
                }
            ]
	}, 
        {
	    "AppointmentId" : null,           
            "ProductId" : "5c2e5d752604a7013cbc0339", 
            "Description" : "S&H", 
            "TotalTaxAmount" : 0, 
            "Units" : 1, 
            "Price" : 13.15,
            "TotalAmount": 13.15
	    "Date" : null, 
            "Taxes" : [], 
            "TaxesIncludedInPrice" : false, 
            "IsCopay" : false, 
            "ServiceCode" : "SH", 
            "SubItems" : [
            ]
	}
   ],
   DiagnosisList: ["DX1", "DX2"]
}

Let’s look at each property individually:

Field Explanation
Id The ID of the invoice.
ClientName The name of the client.
ClientEmail
The email of the client.
ClientIdNumber The client's ID assigned by IntakeQ.
Number The invoice number.
IssueDate The date when the invoice was issued.
Status Possible values:
Draft – The invoice has been created but not issued.
Unpaid – The invoice has been issued and has not been paid.
PastDue – The invoice has past the payment date and the customer has not paid. 
Paid – The invoice has been paid by the customer.
Refunded – The invoice has been refunded by the staff. 
Canceled - The Invoice has been voided.
DueDate
The date when when the invoice is due.
CurrencyIso
The currency of the invoice
DiscountPercent 
The discount value in percent applied on the invoice.
DiscountAmount
The discount amount in percent applied on the invoice.
DiscountType
Percent or Amount.
Subtotal
The sum of all the items.
TotalAmount
The final amount of the invoice, after taxes and discounts.
AmountDue
The unpaid amount. 
AmountPaid
The paid amount.
NoteToClient
Notes to the client
TipAmount
The tip amount.
Automated Created automatically by IntakeQ
AdditionalEmailRecipients Send the invoice to multiple recipients
DateCreated When the invoice was created in Unix timestamp.
CreatedBy The name of the person who created the invoice. It can be the name of a client or of a staff member.

Item.Quantity Item Quantity

Item.Description Item Description

Item.Units Item Units

Item.Price Item Price

Item.Date Item Date

Item.TaxesIncludedInPrice Check if the taxes are included in the price

Item.IsCopay Check if the item has a copayment

Item.SubItem.ServiceCode Subitem Service Code

Item.SubItem.Price Subitem Price


Item.SubItem.Quantity Subitem Quantity

Item.SubItem.Units Subitem Units

Item.SubItem.Description Subitem Description

Payments.Date When the payment has been made

Payments.Amount Payment amount

Payments.Currency Payment Currency

Payments.Method Stripe, CreditCard, Cash, Check, DebitCard, Square, CreditBalance, BankTransfer, Insurance, GiftCard, Other

Payments.ProcessedBy The name of the person who processed the payment. It can be the name of a client or of a staff member.

Query Invoices

Use this method to query invoices in your organization. The results will be ordered by Date in descending order.

[GET]
/invoices?clientId=[clientIdNumber]&startDate=[yyyy-MM-dd]&endDate=[yyyy-MM-dd]&status=[status]&practitionerEmail=[practitionerEmail]&number=[number]&page=[pageNumber]

This method accepts the following query string parameters:

  • clientId (optional) – An integer used to search the client by ID. 
  • startDate (optional) – Return only invoices that are scheduled for after the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • endDate (optional) – Return only invoices that are scheduled for before the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • status (optional) – Possible values are "Draft", "Scheduled", "Unpaid", "Paid", "PastDue", "Refunded", "Forgiven" and "Canceled".
  • practitionerEmail (optional) – Use this to get invoices for a specific practitioner. The email must match the email used in the practitioner IntakeQ account. If empty, invoices for all practitioners in the organization will be returned.
  • page (optional) – This method returns a maximum of 100 records. Use the page parameter to implement paging from your end. Use 1 for page 1, 2 for page 2, etc.
  • lastUpdateStartDate (optional) – Return only invoices that have been changed after the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • lastUpdateEndDate (optional) – Return only invoices that have been changed before the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)

This method returns a JSON object representing an array of invoices.

[{
    Id: "123", 
   Number: 123,
   ClientName: "test",
   ClientEmail: "test@email.com",  
   ClientIdNumber: 9999,
   Status: "Paid", // Unpaid, Paid, PastDue
   IssuedDate: 1458526480368, //Unix timestamp,
   DueDate: 1458526484236, //Unix timestamp,
   DateCreated: 1458526484236, //Unix timestamp,
   CurrencyIso: "USD",
   DiscountAmount: 3.45,
   DiscountPercent: 0.20, 
   DiscountType: "Percentage", // Percentage, Amount
   SubTotal: 163.50,
   TotalAmount: 163.50,
   AmountDue: 60,
   AmountPaid: 80,
   NoteToClient: "Thank you to choose IntakeQ",
   AllowTipping: true,
   TipAmount: 18,
   Automated: true,
   CreatedBy: "Dr. Test",
   AdditionalEmailRecipients: ["test2@email.com"],
   Payments: [],
   Items: []
},...
]

This method returns a maximum of 100 records. If needed, use the page query string parameter to implement paging from your end.

Use this method to get a single invoice using its ID.

[GET] https://intakeq.com/api/v1/invoices/[invoice-id]

Refer to the invoice object above for its JSON representation.

Invoice Webhook

You can subscribe to invoice events in the API settings page.

If you populate the webhook URL in the API settings page, we will send the following JSON object in a POST message every time an invoice is issued or paid:

   {
      EventType: "InvoiceIssued",
      ActionPerformedByClient: true,
      Invoice: { .... } //refer to the invoice object above
   }

Let’s look at each property individually:


Field Explanation
EventType Describes which action triggered this event. Possible values:
InvoiceIssued - triggered once when the invoice is initially created.
InvoicePaid - triggered when the invoice has been paid by the customer.
InvoicePaymentPlanChargeFailed - triggered when a recurring payment plan charge has failed.
InvoiceAutoChargeFailed - triggered when an appointment auto-charge has failed.
InvoiceCancelled - triggered when an invoice has been canceled.
InvoicePaymentRefunded - triggered when an invoice payment has been refunded.
ActionPerformedByClient Boolean value indicating whether the action was performed by a client or by a staff member.
Invoice The invoice object as defined above.

Still need help? Contact Us Contact Us