api login

In addition to allowing you to perform basic crud operations on invoices, BigTime's invoice api enables you to pull lists of invoices by period or status as well.

Invoice dta can be fairly detailed, so the list information you pull will return data only in the "simple" format. You can then pull individual invoice detail(s) for the invoices you need to see in the Detailed format (one at a time). Just like the rest of the API documentation, this page has a list of all the fields that can be returned with an invoice request, and each field is flagged as Simple, Detailed or both.

Finally, keep in mind that invoices can be attached to specific time/expense entries. It is possible to pull a list of time/expnese entries attached to a specific invoice using this section of the api. The data you get back will follow the format outlined in the time/expenses section of the api.

Invoice Lists

When you get a list of invoices -- you can pull them for a specific time period, or you can pull all of the 'draft' invoices in the system (eg - invoices that have not been marked SENT yet). In addition, BigTime supports some basic filtering as well. Those calls are documented here.

Getting Invoices by Date Range

By submitting a simple query to this api, you'll get a listing of invoice data (we return the "simple" view on the listings page). Note that startDt and endDt are both required parameters.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /invoice/history?startDt={YYYY-MM-DD}&endDt={YYYY-MM-DD}
HTTP RESPONSE:  (array of Invoice objects ("simple" view -- see below for details)

Getting All Draft Invoices
try it
  • Click the GET button below to view the information returned by this url.

  • Get

By submitting a simple query to this api, you'll get a listing of invoice data (we return the "simple" view on the listings page). Note that you have the option of including startDt and endDt in order to limit the list returned by the system.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /invoice/drafts?[startDt={YYYY-MM-DD}]&[endDt={YYYY-MM-DD}]
HTTP RESPONSE:  (array of Invoice objects ("simple" view -- see below for details)

Getting Invoices by Client Id

By passing in a Client Id and date range, you will get a list of invoices for that client that were created between the specified date range.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /invoice/GetInvoicesByClientId?[clientid={0}&startDt={YYYY-MM-DD}]&[endDt={YYYY-MM-DD}]
HTTP RESPONSE:  (array of Invoice objects ("simple" view -- see below for details)

Working with Individual Invoices

Pulling the detail for a specific invoice.

You can use a simple GET request to pull the details associated with a single invoice. Note that the DETAILED view fields will be returned for your request. You should also note that a user cannot pull invoice data for an entity they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /invoice/detail/{sid}
HTTP RESPONSE:  a single DETAILED object (see below for details)

Creating a New Invoice.

When you create a new invoice, you simple specify the project for which the invoice should be created and the InvoiceType (eg - the type of calculator you want to use to generate the invoice).

BigTime supports a wide variety of invoice calculators, and BigTime customers can create their own invoice calculators as well. In addition, you can create an empty ("manual") invoice and add line items to that invoice as needed.

To create an empty ("manual" invoice, pass the invoice type of 0). To create a Time/Material invoice, pass the invoice type of 1. For additional invoice types, take a look at the CalculatorTypes restful request at the end of this page.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /invoice/create?projectSid={projectSid}&invoiceType={calculatorType}
HTTP RESPONSE:  InvoiceDetail object (see below)

Updating Existing Invoices Entries.

Note that only the fields listed in the AddUpdate view (below) should be included in your post to this url. Any other data will be ignored. Note again, validation errors will return a 400 error, and an invalid permission will return a 405 (eg - you must have management rights to any project for which you are attempting to create an invoice).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /invoice/detail/{sid}
POST CONTENT:  {Status: 'Sent', 
		Note1: "this is an updated note..."}
		
** You can include ANY of the AddUpdate fields below.  
		Do not "zero-out" or remove any of the required (*) fields.

HTTP RESPONSE:  (updated Invoice object -- see below for details)
Updating Invoice Line Items

Invoice line items each have a unique LineNbr value, and we use that value when you update your invoice in order to update line items. You can add new line items by including a LineNbr value of 0 for the new entry.

Note that excluding a line from your post will not delete it. For an update, you only need to post the fields you are attempting to update, so not every invoice/detail post will contain all of the line items attached to an invoice. For that reason, we've included an IsDeleted property for each line item in the invoice. Sending a TRUE to that property will remove the line item.

Adding/removing line items will change the lineNbr value for the remaining items, so make sure that you note the new line numbers when you post this type of update.

Deleting an Invoice.

As long as the user has management rights for the project to which an invoice is attached, BigTime will allow you to delete it.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /invoice/detail/{sid}
HTTP RESPONSE:  200 is a successful delete.

Invoice Object: Field Details

For each of the operations listed above, you will post or "get" one or more invoice objects. The list below is a complete catalog of fields available through the api (including the views within which those fields are found). Take special note of the AddUpdate view. Required fields are flagged with an "*" character.

FieldTypeDescriptionView(s)
Sid Integer Unique SID code for this record. Detailed, AddUpdate*
ClientSid Integer Unique SID code for the client to which this invoice is attached. Detailed, AddUpdate*
ProjectSid Integer Unique SID code for the project to which this invoice is attached. Detailed, AddUpdate*
ProjectLinkValue String If you know a project's full displayName or it's Id, but not the project's SystemId, then you can still create an invoice. Just use this alternate property instead of the ProjectSid field and BigTime will automatically LOOKUP the correct ProjectSid value for you.

We match ProjectLink value (in order) against these fields: ProjectCode, DName

AddUpdate*
ClientNm String Name of the client to which this invoice is attached. Detailed
DName String "display name" of the project to which this invoice is attached. Detailed
BillingContactId Integer Unique SID code for billing contact the invoice should be addressed to (eg - the project's main billing contact). Detailed, AddUpdate*
ContactLinkValue String If you know a contact's name or email, but not the contact's SystemId, then you can still link an invoice to a billing contact. Just use this alternate property (instead of BillingContactId), and BigTime will automatically LOOKUP the correct BillingContactId for you.

When we do, we lookup contacts using these fields: Contact EMail, Contact First+Last name, Contact Last name.

AddUpdate*
Calculator Integer The id for the invoice calculator type used to generate this invoice (this is the same as the invoiceType parameter used to create the invoice). Detailed
CanEditInvoice True/False TRUE if this user has rights to edit the invoice. Detailed
InvoiceNbr String Invoice "number" which the customer will see on the printed invoice. Detailed, AddUpdate*
InvoiceDt Date DATE for the invoice (eg - the date that appears on the printed invoice). Note that this will default to the DRAFT date unless the user changes that value when the invoice is posted to their accounting system (often - invoices are drafed a few days after the end of a given month, but they are "dated" for the last day of the month). Detailed, AddUpdate*
InvoiceAmt Numeric AMOUNT in tblInvoice (note that this property is pulled for the invoice Simple view, and is the same as TotalAmt in the detailed view). Detailed
Subtotal Numeric TOTAL of line item amounts. This is the invoice amount NET OF TAXES and DISCOUNTS. Detailed
TotalAmt Numeric The invoice "amount due". This is the invoice amount INCLUDING TAXES and DISCOUNTS. Detailed
PaidAmt Number The total amount PAID on this invoice (TOTAL AMOUNT DUE should be TotalAmt-PaidAmt) Detailed, AddUpdate*
SalesTaxAmt Numeric Total amount of SALES TAXES on this invoice (see SalesTaxList for details). Detailed
InvoiceDtSt Date If the invoice was created for a specific PERIOD, then this field contains that period's start date. Detailed, AddUpdate*
InvoiceDtEnd Date If the invoice was created for a specific PERIOD, then this field contains that period's end date. Detailed, AddUpdate*
InvoiceDtSent Date Date this invoice was POSTED (eg - recorded and sent to the client. THIS is the date that we post to QuickBooks or other accounting packages). Detailed, AddUpdate*
Note1 String Invoice note (first field) 500 characters long. Detailed, AddUpdate*
Note2 String Invoice note (second field) 500 characters long. Detailed, AddUpdate*
PONumber String Detailed, AddUpdate*
Status EnumValue This value should be one of the following: Drafted, Approved, Posted, Sent, Paid Detailed, AddUpdate*
StatusTxt String String version of the Status field. Detailed
ARAcctSid Integer Unique SID code for the AR account to which this invoice will post (note that we get this value from the customer's accounting system). Detailed, AddUpdate*
SalesTaxSid Integer if this is a US-based invoice, then this value is the sales tax rate applied to the overall invoice. Detailed, AddUpdate*
TermsSid Integer Unique SID code for the INVOICE TERMS (eg - net 30, 60, 90). Updating an invoice's TERMS value will change it's due date automatically. Detailed, AddUpdate*
TermsLinkValue String If you don't know the Unique SID code for a specific "terms" value, then you can still specify terms, just specify the "name" of the invoice term in this field and BigTime will lookup the proper TermsId for you. AddUpdate*
InvoiceDtDue Date Due date Detailed, AddUpdate*
PostedStatus String One of the following values: none, Unposted, Pending, Successful, Failed, InProcess, Invalid Detailed
BillingAddress (Address) The TO address for this invoice. Detailed, AddUpdate*
FirmAddress (Address) The FROM address for this invoice. Detailed, AddUpdate*
Lines (LineItem) Invoices are made up of Line Items, and this property is an array of invoice LineItem objects. See the line item object for more details on what each object in this array will look like. Detailed, AddUpdate*
salesTaxList (TaxItems) See SalesTax object below for details. Detailed
Address Object Field Details

FieldTypeDescriptionView(s)
Address String Street address (can be multi-line) Detailed, AddUpdate
City String Detailed, AddUpdate
State String State, Province or county (depending on the address' country of origin) Detailed, AddUpdate
Zip String Postal code Detailed, AddUpdate
Country String Country of origin. Detailed, AddUpdate
Invoice Line Item Object Details

FieldTypeDescriptionView(s)
LineNbr Integer Detailed, AddUpdate
Nm String Detailed, AddUpdate
Nt String Detailed, AddUpdate
AcctSid Integer Detailed, AddUpdate
BudgetPer Integer Detailed, AddUpdate
IsCredit True/False Detailed, AddUpdate
IsNonTimeCharge True/False Detailed, AddUpdate
IsTaxable True/False Detailed, AddUpdate
QBClassSid Integer Detailed, AddUpdate
Quantity Numeric Detailed, AddUpdate
Rate Numeric Detailed, AddUpdate
Amt Numeric Detailed, AddUpdate
SalesTaxSid Integer Detailed, AddUpdate
SubTotalSID Integer Detailed, AddUpdate
UpdatedLineNbr Integer AddUpdate
IsDeleted True/False Include this property and a value of TRUE in order to remove an existing line item. AddUpdate
AcctSidNm String Detailed
InvoiceSid Integer Detailed
LineType Integer Detailed
ProjectSid Integer Detailed
QBClassNm String Detailed
SalesTaxAmt Numeric Detailed
SalesTaxNm String Detailed
Source Integer Detailed
Invoice SalesTax Line Object Details

If an invoice includes sales tax, then each line item is marked with the tax rate it should be billed at. Then, when the invoice is pulled, a list of "sales tax lines" is included (in the format shown below).

FieldTypeDescriptionView(s)
taxSid Integer Detailed
taxNm String Detailed
taxRt Numeric Detailed
taxAmt Numeric Detailed