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"],
   ClientPaymentPlanId: ""
   ClientPaymentPlanInterval: 0,
   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
ClientPaymentPlanId	The ID of the payment plan that created the invoice. It will be null when the invoice is not associated with a payment plan.
ClientPaymentPlanInterval	If this invoice is associated with a payment plan, this field informs which period the invoice is for. This is a zero-based index, so the first period is 0, the second period is 1, and so on.
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.
lastUpdatedStartDate (optional) – Return only invoices that have been changed after the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
lastUpdatedEndDate (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.