Introduction
Welcome to the help page of the Saasu application programming interface (API). Here you will find documentation around usage of the API that is relevant to application developers and consumers who wish to integrate with Saasu via the API.
This is a rest based API, and the interface currently supports submitting and returning data in both XML and JSON data formats. This can be specified by the consumer by using the content-type http header when submitting API calls. This header value can be either application/json for JSON formatted data or application/xml for XML structured data (see below for further details)
Authentication
This interface supports two methods of authentication and authorisation to allow access to Saasu via this interface. The use of wsAccessKey and FileId on the URL as arguments (detailed below), and the use of OAuth 2 protocol method, which is the preferred method of authentication and authorisation as it provides many advantages over the former, not the least of which is being more secure. It requires a different form of handshaking when interacting and is detailed in this section on authentication.
API Limits and System Requirements
API Fair Play Limits by plan can be found here along with other system requirements.
Versioning
The Saasu API supports prior versions of API calls where required. It is recommended that all API calls provide a version number in every call. API calls that do not specify a version, will simply return the latest version of the API call.
The current version number is: 1.0
Most API changes will be backwards compatible with non breaking changes. Where breaking changes are made, prior versions of the those API calls will be made accessible and indicated in the documentation.
For more information on versioning usage and details on how to access prior versions of the API, please see this section
Hypermedia
This API supports the notion of Hypermedia or self discovery via resource links. This has been linked with the concept known as HATEOAS. In its most basic form, this means that on every API call, you will always receive a set of 'link' elements that tell you what you can also link to for other API calls relevent to the API call you are making. You can get more information here
Client/Proxy Code
There is a sample client, or proxy code that is provided with this API to allow use of an easy, purpose built library to integrate into your applications and consume this API. Currently this client is only written in .Net. The download for the full source code of the client/proxy and further details can be found here.
API Endpoint Summary
- Items to note:
-
- [ .. ] in the documentation denotes optional parameters
- All dates are specified in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Where only the date component is required use YYYY-MM-DD.
Accounts
| Api Call | Description |
|---|---|
| GET Accounts ?IsActive={1|0|true|false|yes|no}&IsBankAccount={1|0|true|false|yes|no}&AccountType={Income|Expense|Asset|Equity|Liability|OtherIncome|OtherExpense|CostOfSales}&IncludeBuiltIn={1|0|true|false|yes|no}&HeaderAccountId={111}&AccountLevel={detail|header} &FileId=#####[&wsAccessKey=XXXXX] | Returns an AccountListResponse object which contains a list of Account Detail records. |
| GET Accounts/BankAccountBalances ?FileId=#####[&wsAccessKey=XXXXX] | Gets a list of bank account balances. |
| GET Account/Id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves a single account. |
| DELETE Account/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an account. |
| POST Account ?FileId=#####[&wsAccessKey=XXXXX] | Insert an account. |
| PUT Account/id ?FileId=#####[&wsAccessKey=XXXXX] | Update an account. |
Activities
| Api Call | Description |
|---|---|
| GET Activities ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&SearchText={some text (max 128 characters)}&ActivityStatus={todo|done|overdue}&ActivityType={Any tags with activity flag set to true}&OwnerEmail={email@somewhere.com} &FileId=#####[&wsAccessKey=XXXXX] | Returns a list of activity summary records. |
| GET Activity/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single activity detail record. |
| POST Activity ?FileId=#####[&wsAccessKey=XXXXX] | Insert an activity. |
| PUT Activity/id ?FileId=#####[&wsAccessKey=XXXXX] | Update an activity. |
| DELETE Activity/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an activity. |
Attachments
| Api Call | Description |
|---|---|
| POST InvoiceAttachment ?FileId=#####[&wsAccessKey=XXXXX] | Inserts an attachment for the specified File and User. |
| GET InvoiceAttachment/id ?FileId=#####[&wsAccessKey=XXXXX] | Returns the attachment with the given attachment Id. |
| DELETE InvoiceAttachment/id ?FileId=#####[&wsAccessKey=XXXXX] | Deletes an attachment with the specified attachment Id. |
| GET InvoiceAttachments/Id ?FileId=#####[&wsAccessKey=XXXXX] | Gets all the information around attachments for a given invoice id. Does not return the attachment itself, just the metadata/information regarding all attachments. |
Company
| Api Call | Description |
|---|---|
| GET Company/Id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves the details for a single company. |
| GET Companies ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&CompanyName={some text} &FileId=#####[&wsAccessKey=XXXXX] | Retrieves a list of companies. |
| DELETE Company/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a company. |
| POST Company ?FileId=#####[&wsAccessKey=XXXXX] | Insert a company. |
| PUT Company/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a company. |
Contacts
| Api Call | Description |
|---|---|
| GET Contacts ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&GivenName={some text}&FamilyName={some text}&CompanyName={some text}&CompanyId={some text}&IsActive={1|0|true|false|yes|no}&IsCustomer={1|0|true|false|yes|no}&IsSupplier={1|0|true|false|yes|no}&IsContractor={1|0|true|false|yes|no}&IsPartner={1|0|true|false|yes|no}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&Email={email@somewhere.com}&ContactId={some text} &FileId=#####[&wsAccessKey=XXXXX] | Gets a list of contacts for a given file. |
| GET Contact/id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves an individual contact. |
| GET Contact/id/generate-pdf ?FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&GenerateType={Statement} &FileId=#####[&wsAccessKey=XXXXX] | Returns a response with raw PDF file content for a specified generate type related to a contact. |
| DELETE Contact/Id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a Contact. |
| POST Contact ?FileId=#####[&wsAccessKey=XXXXX] | Insert a contact. |
| PUT Contact/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a contact. |
| GET ContactAggregate/id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves the details for a contact aggregate, consisting of the contact and its associated company and contact manager. |
| POST ContactAggregate ?FileId=#####[&wsAccessKey=XXXXX] | Insert a contact aggregate. Inserts the contact and inserts or updates the associated company and contact manager. |
| PUT ContactAggregate/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a contact aggregate. Updates a contact and inserts or updates the associated company and contact manager. |
DeletedEntities
| Api Call | Description |
|---|---|
| GET DeletedEntities ?EntityType={Sale|Purchase|SalePayment|PurchasePayment|Item|Contact|Journal}&UtcDeletedFromDate={YYYY-MM-DD}&UtcDeletedToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Get deleted entities. |
FileIdentity
| Api Call | Description |
|---|---|
| GET FileIdentity ?FileId=#####[&wsAccessKey=XXXXX] | Returns a single File Identity Detail record. |
| GET FileIdentities [?wsAccessKey=XXXXX] | Returns a list of File Identity Summary records. |
| PUT FileIdentity ?FileId=#####[&wsAccessKey=XXXXX] | Update File Identity. |
Invoices
| Api Call | Description |
|---|---|
| GET Invoices ?InvoiceNumber={123}&PurchaseOrderNumber={123}&LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&TransactionType={S|P}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&InvoiceFromDate={YYYY-MM-DD}&InvoiceToDate={YYYY-MM-DD}&InvoiceStatus={I|Q|O}&PaymentStatus={P|U|A}&ContactId={some text} &FileId=#####[&wsAccessKey=XXXXX] | Returns a list of Invoice transaction summary records. |
| GET Invoice/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single Invoice Transaction Summary Record. |
| GET Invoices/SalesStatsSummary ?InvoiceFromDate={YYYY-MM-DD}&InvoiceToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Returns invoices statistics/summary for a date period |
| GET Invoice/id/generate-pdf ?TemplateId={123}&PrintAs={numeric value for sale transaction acceptable values: <4 (Sale)|93 (Quote)|99 (Sale Order)|98 (Shipping Slip)> for purchase: <7 (Purchase)|95 (Quote)|100 (PurchaseOrder)>} &FileId=#####[&wsAccessKey=XXXXX] | Returns a response with raw PDF file content for the invoice. |
| DELETE Invoice/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an invoice. |
| POST Invoice ?FileId=#####[&wsAccessKey=XXXXX] | Insert an invoice. |
| PUT Invoice/id ?FileId=#####[&wsAccessKey=XXXXX] | Update an invoice. |
| POST Invoice/id/email-contact ?FileId=#####[&wsAccessKey=XXXXX] | Email an invoice to the billing contact. |
| POST Invoice/id/email ?FileId=#####[&wsAccessKey=XXXXX] | Email an invoice to the specified email address. |
Items
| Api Call | Description |
|---|---|
| GET ItemTransfers ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Retrieves a list of item transfers. |
| GET ItemTransfer/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single item transfer record. |
| POST ItemTransfer ?FileId=#####[&wsAccessKey=XXXXX] | Insert an item transfer. |
| PUT ItemTransfer/id ?FileId=#####[&wsAccessKey=XXXXX] | Update an item transfer. |
| DELETE ItemTransfer/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an item transfer. |
| GET Items ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&IsActive={1|0|true|false|yes|no}&ItemType={I|C}&SearchMethod={Contains|StartsWith}&SearchText={some text (max 128 characters)} &FileId=#####[&wsAccessKey=XXXXX] | Retrieves a list of items. |
| GET Item/id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves a single item. |
| POST Item ?FileId=#####[&wsAccessKey=XXXXX] | Insert an inventory item. |
| PUT Item/Id ?FileId=#####[&wsAccessKey=XXXXX] | Update an inventory item. |
| POST Item/id/build ?FileId=#####[&wsAccessKey=XXXXX] | Build a quantity of a combo item. |
| DELETE Item/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an inventory item. |
| GET ItemAdjustments ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Retrieves a list of item adjustments. |
| GET ItemAdjustment/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single inventory item adjustment. |
| POST ItemAdjustment ?FileId=#####[&wsAccessKey=XXXXX] | Create an item adjustment |
| PUT ItemAdjustment/id ?FileId=#####[&wsAccessKey=XXXXX] | Update an item adjustment |
| DELETE ItemAdjustment/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete an item adjustment. |
Journals
| Api Call | Description |
|---|---|
| GET Journals ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&Tags={tag1,tag2}&TagSelection={requireAll|requireAny|excludeAll|excludeAny}&FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&JournalContactId={123} &FileId=#####[&wsAccessKey=XXXXX] | Returns a list of journal transaction summary records. |
| GET Journal/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single journal transaction detail record. |
| DELETE Journal/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a journal. |
| POST Journal ?FileId=#####[&wsAccessKey=XXXXX] | Insert a journal. |
| PUT Journal/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a journal. |
LookupData
| Api Call | Description |
|---|---|
| GET LookupData/IndustryTypes ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of industry types as used in sign up & file identity screens. |
| GET LookupData/Countries ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of countries. |
| GET LookupData/Zones ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of file zones / tax jurisdictions. |
| GET LookupData/Currencies ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of currencies. |
| GET LookupData/DateFormats ?FileId=#####[&wsAccessKey=XXXXX] | [DEPRECATED] Returns a list of date formats. |
| GET LookupData/NumberFormats ?FileId=#####[&wsAccessKey=XXXXX] | [DEPRECATED] Returns a list of number formats. |
OAuth
| Api Call | Description |
|---|---|
| GET authorisation/token | Request an access token using the password credential grant process. Visit the documentation area on authentication for detailed explanation. Requires that the grant request be performed using a GET request and URL parameters. This is NOT the preferred method and using a POST request is preferred |
| POST authorisation/token | Request an access token using the password credential grant process. Visit the documentation area on authentication for detailed explanation. Requires that the grant request be performed using a POST request. This is the preferred method. |
| POST authorisation/token-2fa | Request an access token using the password credential grant process. Visit the documentation area on authentication for detailed explanation. Requires that the grant request be performed using a POST request. This is the preferred method. If user has Two-Factor Authentication (2FA) enabled, the API will SMS the one-time password (OTP) / 2FA code to user's registered mobile number and return a 401 "2fa_code_required" error. Repost the request with the 2FA code to get the access token. |
| POST authorisation/refresh | Refresh an access token using a previously issued refresh token. Visit the documentation area on authentication for detailed explanation. |
| GET authorisation/ping | This is provided simply to be able to test whether the access/bearer token issued is valid |
Payments
| Api Call | Description |
|---|---|
| POST Payment ?FileId=#####[&wsAccessKey=XXXXX] | Insert a Payment transaction. |
| PUT Payment/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a Payment transaction. |
| DELETE Payment/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a Payment transaction. |
| GET Payment/id ?FileId=#####[&wsAccessKey=XXXXX] | Return a single Payment transaction record. |
| GET Payments ?LastModifiedFromDate={YYYY-MM-DD}&LastModifiedToDate={YYYY-MM-DD}&ForInvoiceId&ClearedFromDate={YYYY-MM-DD}&ClearedToDate={YYYY-MM-DD}&TransactionType={SP|PP}&PaymentFromDate={YYYY-MM-DD}&PaymentToDate={YYYY-MM-DD}&PaymentAccountId={123} &FileId=#####[&wsAccessKey=XXXXX] | Returns a list of Payment summary records. Use ForInvoiceId={InvoiceId} to retrieve payments for a single invoice. Note: TransactionType filter will be ignored if ForInvoiceId is specified. |
Payroll
| Api Call | Description |
|---|---|
| GET Payroll/PayrollEntries ?FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&EmployeeId={123} &FileId=#####[&wsAccessKey=XXXXX] | Returns a paged list of payroll entries, sorted by date descending. Employee self service user can only access their own payroll entries / payslips. |
| GET Payroll/Payslip/id/generate-pdf ?FileId=#####[&wsAccessKey=XXXXX] | Returns a PDF payslip. Employee self service user can only access their own payroll entries / payslips. |
| GET Payroll/Timesheet/id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieves a single timesheet entry. |
| POST Payroll/Timesheet ?FileId=#####[&wsAccessKey=XXXXX] | Insert a timesheet entry. |
| PUT Payroll/Timesheet/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a timesheet entry. |
| DELETE Payroll/Timesheet/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a timesheet entry. |
| GET Payroll/Employees ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of all employees in file including inactive. Valid filters: IsActive, IncludeLeaveBalances, LeaveBalanceAsAtDate. To include leave balances for each employee, add "IncludeLeaveBalances=true" in the URI Parameters. |
| GET Payroll/Employee/id ?FileId=#####[&wsAccessKey=XXXXX] | Returns a single employee in file including inactive. Valid filters: IsActive, IncludeLeaveBalances, LeaveBalanceAsAtDate. To include leave balances for employee, add "IncludeLeaveBalances=true" in the URI Parameters. |
| GET Payroll/Entitlements ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of entitlement / leave pay items. |
| GET Payroll/LeaveRequest/id ?FileId=#####[&wsAccessKey=XXXXX] | Retrieve a single leave request entry. |
| POST Payroll/LeaveRequest ?FileId=#####[&wsAccessKey=XXXXX] | Insert a leave request. |
| PUT Payroll/LeaveRequest/id ?FileId=#####[&wsAccessKey=XXXXX] | Update a leave request. |
| DELETE Payroll/LeaveRequest/id ?FileId=#####[&wsAccessKey=XXXXX] | Delete a leave request. |
Reports
| Api Call | Description |
|---|---|
| GET Reports/ProfitAndLoss/SummaryByAccountType ?FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&AccountingMethod={Accrual|Cash}&ComparisonPeriodFromDate={YYYY-MM-DD}&ComparisonPeriodToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Get Profit and Loss (P&L) Summary Report, grouped by account type. If no accounting method specified, it will default to accrual mode. If no date range specified, it will default to current financial year. |
| GET Reports/ProfitAndLoss/Summary ?FromDate={YYYY-MM-DD}&ToDate={YYYY-MM-DD}&AccountingMethod={Accrual|Cash}&ComparisonPeriodFromDate={YYYY-MM-DD}&ComparisonPeriodToDate={YYYY-MM-DD} &FileId=#####[&wsAccessKey=XXXXX] | Get Profit and Loss (P&L) Summary Report. If no accounting method specified, it will default to accrual mode. If no date range specified, it will default to current financial year. To compare to different period, e.g. prior corresponding period, specify the comparison period from and to date. When doing comparison, the main report period should be later than the comparison period. E.g. To compare the P&L for a particular FY with prior corresponding period (pcp), call the report with the following settings: - Main period: 1 Jul 2022 - 30 Jun 2023. - Comparison period: 1 Jul 2021 - 30 Jun 2022. |
Search
| Api Call | Description |
|---|---|
| GET Search ?Keywords={some text}&Scope={All|Transactions|Contacts|InventoryItems}&TransactionType={Transactions.Sale|Transactions.Purchase|Transactions.Journal|Transactions.Payroll}&IncludeSearchTermHighlights={1|0|true|false|yes|no} &FileId=#####[&wsAccessKey=XXXXX] | Search for Transactions, Contacts and Inventory Items that have been indexed by the search platform. |
Settings
| Api Call | Description |
|---|---|
| GET TaxCodes ?IsActive={1|0|true|false|yes|no} &FileId=#####[&wsAccessKey=XXXXX] | Returns a list of Tax Code detail records. |
| GET TaxCode/id ?FileId=#####[&wsAccessKey=XXXXX] | Returns a single Tax Code detail record. |
| GET Brands ?FileId=#####[&wsAccessKey=XXXXX] | Returns a list of brands. |
User
| Api Call | Description |
|---|---|
| POST User/reset-password | Request password reset for a user. Initiates the process used to reset a user's password. |
| GET User | Get current user detail. |
| PUT User | Update current user detail. To change the username / email address and password, please call their own separate methods . |
| POST User/opt-in-to-2fa | Opt-in to two-factor authentication (2FA). This will send a one-time password (OTP) to the specified mobile number. You will need to call the method to verify this OTP to activate the 2FA, by the passing in the OTP and the provider user id returned as part of this call. |
| POST User/verify-2fa-opt-in | Verify the 2FA opt-in request by passing in the OTP and ProviderUserId. |
| POST User/opt-out-from-2fa | Opt-out from 2FA. |