Saasu API

Introduction

Saasu’s comprehensive application programming interface (API) allows other software and web applications to interact with Saasu. Just as humans do by creating, reading, updating and deleting transactions. Our API framework has been built in the REST style. All calls are conducted through unified HTTP methods: GET, POST, and DELETE. You’ll need a basic understanding of XML and Schema.

Development and Testing

Develop and test in a free file which have full WSAPI access to the Saasu online accounting engine. Any changes you make here will not affect your live files. Note that Transaction Data cannot be migrated from the test file to a live file. If you are not a current user of Saasu, then sign up for Saasu first. If you are a user of a Saasu subscription already, then you don’t have to sign up for a new subscription.

Sample code and a test file

Grab the open source Saasu REST Client and Sample Application. Sign up for a Saasu account if you haven’t got one. If you already have a Saasu account and want another free file for testing the API, you can create another free account by going to My Saasu > Manage Subscription > Upgrade and add another free file. If you need to test large volumes of data above the free file limit then upgrade to add a 3 month Saasu Medium or Large file to do this.

Important note regarding API work to process payments

Ensure you workflow and development don’t breach PCI DSS compliance if you plan to process credit cards. Saasu isn’t responsible for what you do with this open source code as we have no control over it’s use.

Activating API Access for Your File

You will need a web service access key (WSAccessKey) and file id (FileUid) to access your file through the Web Service API. If you aren’t an admin person for your file you will need to request your admin person to give you access. We have made WSAccessKey’s specific to each user for security reasons. Business owners need accountability and compliance that ensures all API access can be pin-pointed to a specific API user access.

Enable API access for a user to a specific file

  1. Sign in to the File you are setting up access to.
  2. Go to Settings > Web Services.
  3. Tick Turn on web services access for this file and click save.
  4. The API credentials will be revealed after you click the save button.

Create a specific API user for API transactions

  1. While signed into your Saasu file, click on My Saasu in the top menu.
  2. If you don’t automatically go into the Manage Subscription Screen then click on the Manage Subscription link that relates to where you file resides
  3. Pick an existing user as an API user for your file or create a separate user account (recommended).
  4. Click on the user you want to give an API access key to.
  5. In this Edit User screen tick the check box “This user has permission to connect via web services key”.
  6. Click save to reveal the user specific API key.
  7. Click close to go back to Manage Subscription screen.
  8. Click on the file that you want to be made accessible via web service.
  9. In this Edit File screen, tick the check box Allow access to this File via web services and permission the API user to access this file by giving it an appropriate access level.
  10. Click Save to reveal the file id.

Enable a File for API access

  1. Go into My Saasu screen by clicking on My Saasu link on the top right.
  2. Click on the Subscription Name(folder icon) to go into Manage Subscription screen
  3. Click on the edit icon(pencil) adjacent to the file name in the list of files.
  4. When you are in Edit File screen, tick the check box “Allow access to this File via web services”, and click on Save. The Id of the file will now appear adjacent to the check box.

Find a Web Services Access Key for a user

  1. Go into My Saasu screen by clicking on My Saasu link on the top right.
  2. Click on the Subscription Name(folder icon) to go into Manage Subscription screen.
  3. Click on the edit icon(pencil) adjacent to the name of the user in the list of users.
  4. When you are in Edit User screen, tick the check box This user has permission to connect via web services key, and click on Save. This will generate and display your WS Access Key adjacent to the check box.

Web Services URLs

1

https://secure.saasu.com/webservices/rest/r1/Tasks?wsaccesskey={WSAccessKey}&FileUid={FileUid}

HTTP POST Examples

Data processing requests are submitted through HTTP POST request to Tasks resource. Multiple tasks can be submitted at once. The following example illustrates submitting three tasks in a single request:

  • Task #1: update contact (updateContact).
  • Task #2: insert a service sale with quick payment (insertInvoice).
  • Task #3: insert an unpaid item sale (insertInvoice).

Sample request data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <updateContact>
    <contact uid="23985" lastUpdatedUid="AD3872E=">
      <salutation>Mrs.</salutation>
      <givenName>Mary</givenName>
      <familyName>Smith</familyName>
      <organisationName>ACME Pty Ltd</organisationName>
      <organisataionAbn>11 111 111 111</organisationAbn>
      <contactID>223</contactID>
      <organisationWebsite>www.acme.com</organisationWebsite>
      <mobilePhone>0666 666 666</mobilePhone>
      <homePhone> 02 8888 8888</homePhone>
      <tags>Prospect, IT</tags>
      <postalAddress>
        <street>11/111 ABC Av</street>
        <city>Sydney</city>
        <state>NSW</state>
      </postalAddress>
      <otherAddress/>
      <isActive>true</isActive>
   </contact>
 </updateContact>
<insertInvoice emailToContact="false">
  <invoice uid="0">
    <transactionType>S</transactionType>
    <date>2005-09-30</date>
    <contactUid>23986</contactUid>
    <tags>Online Sales, XYZ</tags>
    <summary>Test POST sale</summary>
    <notes>From REST</notes>
    <requiresFollowUp>false</requiresFollowUp>
    <dueOrExpiryDate>2005-12-01</dueOrExpiryDate>
    <layout>S</layout>
    <status>I</status>
    <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
    <purchaseOrderNumber>PO222</purchaseOrderNumber>
    <invoiceItems>
      <serviceInvoiceItem>
        <description>Design and Development of REST WS</description>
        <accountUid>24502</accountUid>
        <taxCode>G1</taxCode>
        <totalAmountInclTax>2132.51</totalAmountInclTax>
      </serviceInvoiceItem>
      <serviceInvoiceItem>
        <description>Subscription to XYZ</description>
        <accountUid>24504</accountUid>
        <taxCode>G1</taxCode>
        <totalAmountInclTax>11.22</totalAmountInclTax>
      </serviceInvoiceItem>
    </invoiceItems>
    <quickPayment>
      <datePaid>2005-09-30</datePaid>
      <dateCleared />0001-01-01</dateCleared>
      <bankedToAccountUid>24509</bankedToAccountUid>
      <amount>100</amount>
      <reference>CASH</reference>
      <summary>Quick payment from Westpac.</summary>
    </quickPayment>
    <isSent>false</isSent>
  </invoice>
</insertInvoice>
<insertInvoice emailToContact="true">
  <invoice uid="0">
    <transactionType>S</transactionType>
    <date>2005-10-06</date>
    <contactUid>23987</contactUid>
    <tags>Online Sales, ABC123</tags>
    <summary>Test Insert Item Sale</summary>
    <notes>From REST</notes>
    <requiresFollowUp>false</requiresFollowUp>
    <dueOrExpiryDate>2005-11-06</dueOrExpiryDate>
    <layout>I</layout>
    <status>I</status>
    <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
    <purchaseOrderNumber>PO333</purchaseOrderNumber>
    <invoiceItems>
      <itemInvoiceItem>
        <quantity>2</quantity>
        <inventoryItemUid>4822</inventoryItemUid>
        <description>Seagate HDD - 300G</description>
        <taxCode>G1</taxCode>
        <unitPriceInclTax>120.75</unitPriceInclTax>
      </itemInvoiceItem>
      <itemInvoiceItem>
        <quantity>5.125</quantity>
        <inventoryItemUid>4821</inventoryItemUid>
        <description>Cat 5 Cable (in meter)</description>
        <taxCode>G1</taxCode>
        <unitPriceInclTax>2.555</unitPriceInclTax>
        </itemInvoiceItem>
      </invoiceItems>
      <quickPayment>
        <datePaid>0001-01-01</datePaid>
        <dateCleared>0001-01-01</dateCleared>
        <bankedToAccountUid>0</bankedToAccountUid>
        <amount>0</amount>
      </quickPayment>
      <isSent>false</isSent>
    </invoice>
    <emailMessage>
      <from>test@acme.com.au</from>
      <to>smith@acme.com.au</to>
      <subject>Invoice</subject>
      <body>Thanks for shopping with us. Attached is a PDF invoice for your record.</body>
    </emailMessage>
  </insertInvoice>
</tasks>

Sample Response (Success):

1
2
3
4
5
6

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse>
    <updateContactResult updatedEntityUid="23985" LastUpdatedUid="1AB72C=" />
    <insertInvoiceResult insertedEntityUid="253490" LastUpdatedUid="90DFDA=" sentToContact="false" generatedInvoiceNumber="A0101"  />
    <insertInvoiceResult insertedEntityUid="253492" LastUpdatedUid="379A9ACD=" sentToContact="true" />
  </tasksResponse>

Sample Response (Error in executing a task):

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse> 
    <updateContactResult updatedEntityUid="24001" LastUpdatedUid="A37CA998" />
    <insertInvoiceResult sentToContact="false">
      <errors>
        <error>
          <type>InvalidReferenceException</type>
          <message>The referenced Contact does not exist.</message>
        </error>
      </errors>
    </insertInvoiceResult><br />
    <insertInvoiceResult insertedEntityUid="253501" LastUpdatedUid="78273DA=" sentToContact="true" />
  </tasksResponse>

Sample Response (Error – invalid task submitted or the XML submitted does not conform to schema):

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse>
    <errors>
      <error>
        <type>SchemaValidationException</type>
        <message>The element "tasks" has invalid content. An error occurred at , (3, 4).</message>
      </error>
    </errors>
  </tasksResponse>

HTTP GET Examples

The following is an example of retrieving a purchase order with uid 253502. Sample request URI:

1

https://secure.saasu.com/webservices/rest/r1/Invoice?wsaccesskey=TEST-888-888&amp;FileUid=888&amp;uid=253502

Sample return (No errors):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<?xml version="1.0" encoding="utf-8"?>
  <invoiceResponse>
    <invoice uid="253502">
      <transactionType>P</transactionType>
      <date>2005-11-24</date>
      <contactUid>24012</contactUid>
      <summary>Test POST Purchase</summary>
      <notes>From REST</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <dueOrExpiryDate>2005-12-24</dueOrExpiryDate>
      <status>O</status>
      <invoiceNumber />
      <purchaseOrderNumber>&lt;Auto Number&gt;</purchaseOrderNumber>
      <invoiceItems>
        <serviceInvoiceItem>
          <description>Purchase - Line Item 1</description>
          <accountUid>24662</accountUid>
          <taxCode>G11</taxCode>
          <totalAmountInclTax>2132.5100</totalAmountInclTax>
          <totalAmountExclTax>1938.6500</totalAmountExclTax>
          <totalTaxAmount>193.8600</totalTaxAmount>
        </serviceInvoiceItem>
        <serviceInvoiceItem>
          <description>Purchase - Line Item 2</description>
          <accountUid>24664</accountUid>
          <taxCode>G11,G15</taxCode>
          <totalAmountInclTax>11.2200</totalAmountInclTax>
          <totalAmountExclTax>10.2000</totalAmountExclTax>
          <totalTaxAmount>1.0200</totalTaxAmount>
        </serviceInvoiceItem>
      </invoiceItems>
      <isSent>false</isSent>
    </invoice>
  </invoiceResponse>

Sample return (with errors):

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
  <invoiceResponse>
    <errors>
      <error>
         <type>RecordNotFoundException</type>
         <message>The requested Invoice is not found.</message>
      </error>
    </errors>
  </invoiceResponse >

HTTP DELETE Examples

For deleting an entity. The following sample illustrates deleting an invoice given the invoice uid. Sample request URI:

1

https://secure.saasu.com/webservices/rest/r1/Invoice?wsaccesskey=TEST-888-888&amp;FileUid=888&amp;uid=251362

Sample return (No errors):

1
2
3
4

<?xml version="1.0" encoding="utf-8">
  <invoiceResponse>
    <deleteResult uid="251362" />
  </invoiceResponse>

List of entities versus a single entity

Requests to “GET List” instead of “GET ” will result in a List of entities instead of a single Entity being returned.
Example: To retrieve a single contact, the query should be sent to:

1

https://.../webservices/rest/r1/Contact?wsaccesskey={YourWSAccessKey}&fileuid={YourFileUid}&uid={ContactUid}

Note that it’s “Contact” not “ContactList”. To retrieve a list of contacts matching certain criteria, make a GET request to ContactList, passing the supported criteria through query string.

If you are using our .NET RestClient Wrapper to make the call, you need to use the “GetByUid” method instead of the “Find” method.
To retrieve a single contact:

1
2

CrudProxy proxy = new ContactProxy();
ContactDto jim = (ContactDto) proxy.GetByUid(99999);

Entities

Unique identifier for every entity
Every entity has a Uid. Here are some of the major entities -

  • Invoice
  • serviceInvoiceItem
  • itemInvoiceItem
  • quickPayment (within Invoice entity)
  • InvoicePayment
  • EmailMessage
  • Contact
  • PostalAddress
  • BankAccount
  • InventoryItem
  • ComboItem
  • InventoryAdjustment
  • Journal
  • JournalItem
  • Activities

When the entity is used in insert tasks set the uid to 0 or don’t specify this element. Saasu will generate a new uid if the entity is inserted successfully. When the entity is used in update tasks, the uid must be > 0 to identify which entity needs to be updated.

The <LastUpdatedUid> identifies when the record was last updated. Saasu generates this value every time the entity is inserted or updated successfully. This value must be specified on update to ensure that no one has updated the record since your last read operation.

When passing data to the web services for boolean values use either true or false. For date values use the following format: yyyy-MM-dd. E.g. Pass 2005-01-16 for 16 January 2005.

Invoice

Invoice covers sales and purchases. This is set through the TransactionType element.
Service and item sale and purchase are supported, which is set through the Layout element.

Sale and purchase can have one of the following three status types; Q (quote), O (order), and I (invoice). The status is set through the Status element.

Payment can be applied to both orders and invoices, but not to quotes.

Rules for invoices:

  • Duplicate invoice number is not allowed.
  • Invoice overpayment is not allowed (e.g. Applying $200 payment to $100 invoice is not permitted).
  • Tax code cannot be applied to Tax Accounts (Asset: Tax Paid on Purchases and Liability: Tax Collected from Sales).
  • Tax code cannot be applied to Bank Accounts.
  • If due date is specified along with trading terms, then trading terms will take precedence over due date to set the actual due date for the invoice being saved.
  • Inserting, updating, and deleting item invoices that have the potential to cause invalid stock level are not permitted. Invalid stock level is defined .
    • Negative stock-on-hand.
    • Negative current value.
    • Stock-on-hand is 0 but current value > 0
    • Current value is 0 but stock on hand > 0.

To retrieve all payments made for an invoice, use incpayments=true in the query string.
To retrieve the invoice in PDF format, use format=pdf in the query string. To retrieve the invoice in PDF format using a specific template, use templateUid=xxxx along with format=pdf.

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String   Y Required for update.
transactionType String   Y Either S for Sale or P for Purchase.
invoiceType String   Y See ‘Invoice Types’ section below for valid values. This varies between zones and whether file is tax registered or not.
date Date   Y The invoice date.
contactUid int     The contact for this invoice. 0 means no contact.
shipToContactUid int     The shipping contact for this invoice. Not specifying or 0 means no shipping contact.
folderUid Int     DEPRECATED.
Use tags instead.
The folder in which the invoice is filed/stored. 0 means unfiled.
tags String     Separate multiple tags by comma. Max length for each tag is 35 characters.
“tags” replaces “folderUid”.
reference String 50   Don’t set this value in invoice because this field is not accessible from the UI.
summary String 75   Brief summary of the invoice
ccy String 3   The currency of the particular invoice transaction.
autoPopulateFxRate Boolean     Indicates whether the FX rate for the invoice was set automatically.
fcToBcFxRate Decimal     The Foreign Currency(FC) to Base Currency(BC) FX Rate. If you are setting the FX rate manually, and only have the BC to FC FX rate, then you should calculate the fcToBcFxRate for posting the transaction. For an example, if your base currency is AUD and 1 AUD = 0.89 USD, get the inverse by 1/0.89. So your fcToBcFxRate = 1.1235.
notes String Unlimited    
externalNotes String     Notes to be displayed on pdf.
requiresFollowUp Boolean      
dueOrExpiryDate Date     Invoice and/or order due date or quote expiry date.
tradingTerms       Used for setting the due date/expiry date for Invoice or Order due date, or Quote expiry date. Takes precedence over dueOrExpiryDate. See tradingTerms section for details.
layout String 1 Y The invoice layout. Either S (Service) or I (Item)
status String 1 Y Leave it blank. Invoice status is either Q (Quote), O (Order) or I (Invoice). We will return the Status code based on the value of the Invoice Type set above.
invoiceNumber String 50   The sale invoice number. When inserting a sale, set to <Auto Number> to let the system generates the invoice number based on the preferences you set.
purchaseOrderNumber String 50   The purchase order number (PO #). When inserting a purchase, set to <Auto Number> to let the system generates the PO# based on the preferences you set.
invoiceItems       You can include unlimited number of invoice items. For service invoice, use <serviceInvoiceItem>. For item invoice: use <itemInvoiceItem>. You cannot mix the content of invoice items (i.e. having both <serviceInvoiceItem> and <itemInvoiceItem>). See <serviceInvoiceItem> and <itemInvoiceItem> section for details.
quickPayment       Payment to be applied to this invoice.
payments       All payments associated with this particular invoice, if incpayments is set to ‘true’ in the query string.
isSent Boolean     Indicates if the invoice has been sent/emailed to contact. This flag will be set to true automatically if the Invoice is sent successfully through the WSAPI.

Invoice Types (Australia)

Invoice Type Status For Sales For Purchases Notes
Pre-Quote Opportunity Q Y Y  
Quote Q Y Y  
Purchase Order O   Y  
Sale Order O Y    
Tax Invoice I Y Y For non tax registered files: Use either ‘Sale Invoice’ or ‘Purchase Invoice’ instead of ‘Tax Invoice’.
Adjustment Note I Y Y  
RCT Invoice I   Y  
Money In (Income) I Y    
Money Out (Expense) I   Y  

Invoice Types (New Zealand)

Invoice Type Status For Sales For Purchases Notes
Pre-Quote Opportunity Q Y Y  
Quote Q Y Y  
Purchase Order O   Y  
Sale Order O Y    
Tax Invoice I Y Y For non tax registered files: Use either ‘Sale Invoice’ or ‘Purchase Invoice’ instead of ‘Tax Invoice’.
Credit Note I Y Y  
Debit Note I Y Y  
Money In (Income) I Y    
Money Out (Expense) I   Y  

Invoice Types (Singapore)

Invoice Type Status For Sales For Purchases Notes
Pre-Quote Opportunity Q Y Y  
Quote Q Y Y  
Purchase Order O   Y  
Sale Order O Y    
Tax Invoice I Y Y For non tax registered files: Use either ‘Sale Invoice’ or ‘Purchase Invoice’ instead of ‘Tax Invoice’.
Credit Note I Y Y  
Debit Note I Y Y  
Self-Billing I   Y  
Money In (Income) I Y    
Money Out (Expense) I   Y  

Invoice Types (USA, UK and Other Zones)

Invoice Type Status For Sales For Purchases Notes
Pre-Quote Opportunity Q Y Y  
Quote Q Y Y  
Purchase Order O   Y  
Sale Order O Y    
Sale Invoice I Y    
Purchase Invoice I   Y  
Credit Note I Y Y  
Debit Note I Y Y  
Payment Invoice I   Y  
Money In (Income) I Y    
Money Out (Expense) I   Y  

serviceInvoiceItem

Line item for service invoice.

Field Type Max. Length Required? Notes
description String Unlimited   Description of service invoice line item. Use pipe (|) character to indicate new line.
accountUid Int   Y The Account for this line item.
taxCode String     Must be one of the tax codes in your file. Invalid tax code will be ignored.
totalAmountInclTax Decimal   Y The total amount (tax inclusive) for this line item. Positive, negative, and 0 are accepted. Maximum 2 decimals.
totalAmountExclTax Decimal     The total amount (tax exclusive) for this line item. This is a read only field and can only be retrieved via HTTP GET.
totalTaxAmount Decimal     The total tax amount for this line item. This is a read only field and can only be retrieved via HTTP GET.

E.g. 5 hours of Income: Technical Support (AccountUid = 273), tax code G1, and hourly rate excluding GST $100 is described in the following xml fragment:

1
2
3
4
5
6
7
8
9

<serviceInvoiceItem>
 <description>5 Hours Technical Support</description>
 <accountUid>273</accountUid>
 <taxCode>G1</taxCode>
<!-- (5 hours x $100/hour) + (10% x (5 hours x $100/hour)) = $550.00 -->
 <totalAmountInclTax>550.00</totalAmountInclTax>
 <totalAmountExclTax>500.00</totalAmountExclTax>
 <totalTaxAmount>50.00</totalTaxAmount>
</serviceInvoiceItem>

itemInvoiceItem

Line item for item invoice.

Field Type Max. Length Required? Notes
quantity Decimal   Y The quantity.
Maximum 3 decimals.
inventoryItemUid Int   Y The inventory item for this invoice line item. This also covers combo item. For combo item, use combo item uid.
description String Unlimited   The description for the line item. Normally, it’s set to inventory item description.
taxCode String     Must be one of the tax codes in your file. Invalid tax code will be ignored.
unitPriceInclTax Decimal   Y Unit price of inventory item.
totalAmountInclTax Decimal   Line item total including tax. This is a read only field and will only be returned as part of a HTTP GET.
totalAmountExclTax Decimal   Line item total excluding tax. This is a read only field and will only be returned as part of a HTTP GET.
totalTaxAmount Decimal   Line item total tax amount. This is a read only field and will only be returned as part of a HTTP GET.
percentageDiscount Decimal     Percentage discount.
E.g. for 10% off the unit price is set the value to 10.
Valid values: between 0 and 100.
Maximum 2 decimals.

E.g. 10 units of Pentium 4 CPU (InventoryItemUid = 920), tax code: G1, unit price including GST before discount is 125.22, and discount: 10% is represented by the following xml fragment:

1
2
3
4
5
6
7
8
9
10
11

<itemInvoiceItem>
 <quantity>10</quantity>
 <inventoryItemUid>920</inventoryItemUid>
 <description>Pentium 4 CPU</description>
 <taxCode>G1</taxCode>
 <unitPriceInclTax>125.22</unitPriceInclTax>
 <totalAmountInclTax>123.97</totalAmountInclTax>
 <totalAmountExclTax>112.70</totalAmountExclTax>
 <totalTaxAmount>11.27</totalTaxAmount>
 <percentageDiscount>10</percentageDiscount>
</itemInvoiceItem>

quickPayment

Field Type Max. Length Required? Notes
datePaid Date   Y When the payment was made.
dateCleared Date     When the payment was cleared.
bankedToAccountUid Int   Y The bank account uid where the payment was banked to.
amount Decimal   Y The payment amount. It must be <= invoice total. Maximum 2 decimals.
reference String 50   Payment reference. It can be used to track cheque #, etc.
summary String 75   Brief summary for this payment.
Leave this blank to let the system sets this automatically.

Invoice Payment

There are two types of Invoice Payment:

  1. Payment for sales (transactionType = SP)
  2. Payment for purchases (transactionType = PP)

An invoice payment can be allocated to multiple invoices regardless of the Contact; as long as they are of the same type (i.e. you cannot have a Sale Payment (SP) transaction and allocate the payment to purchases).

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String   Y Required for update.
transactionType String 2 Y Either SP (Sale Payment) or PP (Purchase Payment).
Date Date   Y The Payment date (received date).
reference String 50   Don’t set this value in invoice because this field is not accessible from the UI.
summary String 75   Brief summary of the invoice.
ccy String 3   The currency of the particular invoice transaction.
autoPopulateFxRate Boolean     Indicates whether the FX rate for the invoice was set automatically.
fcToBcFxRate Decimal     The Foreign Currency(FC) to Base Currency(BC) FX Rate. If you are setting the FX rate manually, and only have the BC to FC FX rate, then you should calculate the fcToBcFxRate for posting the transaction. For an example, if your base currency is AUD and 1 AUD = 0.89 USD, get the inverse by 1/0.89. So your fcToBcFxRate = 1.1235.
notes String Unlimited    
requiresFollowUp Boolean      
paymentAccountUid Int     Bank account uid for the payment. From which bank account the payment is made or to which bank account the payment was banked.
dateCleared       Date when the payment is cleared (normally used for cheque payment).
fee Decimal     Fee amount charged as part of the payment.
invoicePaymentItems       To which invoices is this payment allocated?
See InvoicePaymentItem for details.

Invoice Payment Item

Field Type Max. Length Required? Notes
invoiceUid Int   Y Identifies the invoice where the payment is allocated to.
amount Decimal   Y The payment amount allocated for this invoice. The amount can be positive and negative.
Max. 2 decimals.

EmailMessage

Field Type Max. Length Required? Notes
from String Unlimited Y Only single email address is supported.
to String Unlimited Y Only single email address is supported.
cc String Unlimited   Only single email address is supported.
bcc String Unlimited   Only single email address is supported.
subject String Unlimited    
body String Unlimited    

Contact

At least one of these three fields must be filled on insert/update: givenName, familyName, organisationName.

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String 128 Y Required for update.
salutation String 5   A.K.A “Title”. Valid values; Mr., Mrs., Ms., Dr., Prof.
givenName String 50   A.K.A “First Name”.
middleInitials String 3   A.K.A. “Initial”.
familyName String 50   A.K.A “Last Name”.
organisationName String 75   A.K.A. “Company”.
organisationAbn String 11   A.K.A. “Business Number”.
organisationWebsite String 1024   The organisation/company website url.
organisationPosition String 75    
contactID String 50   This is your own contact ID, different to Saasu’s Contact Uid.
websiteUrl String 1024    
email String 128    
mainPhone String 20    
homePhone String 20    
fax String 20    
mobilePhone String 20    
otherPhone String 20    
tags Spring     Separate multiple tags by comma. Max. length per tag is 35 characters.
postalAddress PostalAddress      
otherAddress PostalAddress      
isActive Boolean     Default: true.
acceptDirectDeposit Boolean      
directDepositAccountName String 75    
directDepositBsb String 6    
directDepositAccountNumber String 20    
acceptCheque Boolean      
chequePayableTo String 75    
customField1 String 50    
customField2 String 50    
twitterID string 100    
skypeID string 100    
      Used for setting the due date/expiry date when creating sales invoices, orders and quotes for contacts. See TradingTerms for more details.
purchaseTradingTerms       Used for setting the due date/expiry date when creating purchase invoices, orders and quotes for contacts. See TradingTerms for more details.
defaultSaleDiscount Decimal     Default discount to be applied when creating a sale for this particular contact.
defaultPurchaseDiscount Decimal     Default discount to be applied when creating a purchase for this particular contact.

Deprecated Fields
The following elements have been deprecated: “statusUid”, “industryUid”. Use “tags” instead.

PostalAddress

Field Type Max. Length Required? Notes
street String 256    
city String 50    
postCode String 12    
state String 50    
country String 50    

Chart of Account

Used to be called “Transaction Category”. API still uses the term “Transaction Category”.

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String 128 Y Required for update.
type String 50 Y Valid value is one of the following:
Income, Expense, Asset, Equity, Liability, Other Income, Other Expense, Cost of Sales
Name String 75 Y  
isActive Boolean     Default: true

BankAccount

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String 128 Y Required for update.
Type String 50 Y Valid value is one of the following:
Asset, Equity, Liability.
Name String 75   Bank account name.
NOTE: Make sure you also set <displayName>.
isActive Boolean     Default: true
displayName String 75 Y Bank account display name.
bsb String 6    
accountNumber String 20    

Inventory Item

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String 128 Y Required for update.
code String 32 Y Inventory item code. Must be unique.
description String 4000 Y Inventory item description.
Multi-line description is supported. Use the pipe (|) to indicate newline.
isActive Boolean     Default: true
notes String Unlimited    
isInventoried Boolean     Specifies whether the inventory item is inventoried or not.
Default: false (not inventoried).
assetAccountUid Int     Required only if IsInventoried is set to true. Accounts used must be of type Asset.
stockOnHand Decimal     How many stocks on hand? This element is only used when you retrieve an Inventory Item from your File. This value is ignored on insert and update.
currentValue Decimal     Current stock value. This element is only used when you retrieve an Inventory Item from your File. This value is ignored on insert and update.
isBought Boolean     Specifies if this item can be bought or not. Default: false (cannot be bought).
purchaseExpenseAccountUid Int     Expense Account for tracking purchase. Required only if the Inventory Item is not inventoried and item can be bought (isInventoried == false && isBought == true). Accounts used must be of type Expense.
purchaseTaxCode String     Default tax code when the inventory item is purchased.
minimumStockLevel Decimal     Minimum stock level used for re-stocking alert report.
primarySupplierContactUid Int     The primary supplier for this Inventory Item.
primarySupplierItemCode String 32   The primary supplier’s item code for this Inventory Item.
defaultReOrderQuantity Decimal     Default re-order quantity for re-stocking alert report.
buyingPrice Decimal     Default buying price for the item. Only applicable if the Inventory Item is marked as bought.
isBuyingPriceIncTax Bool     A flag specifying whether the buying price includes/excludes tax.
isSold Boolean     Specifies whether the Inventory Item can be sold or not. Default: false (cannot be sold).
saleIncomeAccountUid Int     Account for tracking sales. Only required if the item can be sold (isSold == true). Accounts used must be of type Income.
saleTaxCode String     Default tax code for sale.
saleCoSAccountUid Int     Accounts for tracking cost of sales. Required only if Inventory Item is inventoried & for sale. Accounts used must be of type Cost of Sales.
sellingPrice Decimal     The default selling price for this Inventory Item. Only applicable if the Inventory Item is marked as sold.
isSellingPriceIncTax Boolean    
isVirtual Boolean     A flag that indicates this is an item you sell, that you haven’t bought or assembled as stock to make available for sale.
vType String     The type if this item is marked as virtual.
isVisible Boolean     A flag to set the Item to visible, for an example this can be used in your database so that Item is flagged to be displayed in your ecommerce product listings.
isVoucher Boolean     A flag specifying whether this item is treated as a voucher.
validFrom Date     When the voucher becomes effective.
validTo Date     When the voucher expires.

Deprecated Fields
“rrpInclTax” has been deprecated. Please use “sellingPrice” and “isSellingPriceIncTax”.

Combo Item

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String 128 Y Required for update.
code String 32 Y Combo item code. Must be unique.
description String 4000 Y Combo item description.
Multi-line description is supported. Use the pipe (|) to indicate newline.
isActive Boolean     Default: true
notes String Unlimited    
isInventoried Boolean     Specifies whether the Combo item is inventoried or not.
Default: false (not inventoried).
assetAccountUid Int     Required only if IsInventoried is set to true. Accounts used must be of type Asset.
stockOnHand Decimal     How many stocks on hand? This element is only used when you retrieve an Combo Item from your File. This value is ignored on insert and update.
currentValue Decimal     Current stock value. This element is only used when you retrieve an Combo Item from your File. This value is ignored on insert and update.
isBought Boolean     Specifies if this item can be bought or not. Default: false (cannot be bought).
purchaseExpenseAccountUid Int     Expense Account for tracking purchase. Required only if the Combo Item is not inventoried and item can be bought (isInventoried == false && isBought == true). Accounts used must be of type Expense.
purchaseTaxCode String     Default tax code when the Combo item is purchased.
minimumStockLevel Decimal     Minimum stock level used for re-stocking alert report.
primarySupplierContactUid Int     The primary supplier for this Combo Item.
primarySupplierItemCode String 32   The primary supplier’s item code for this Combo Item.
defaultReOrderQuantity Decimal     Default re-order quantity for re-stocking alert report.
buyingPrice Decimal     Default buying price for the item. Only applicable if the Combo Item is marked as bought.
isBuyingPriceIncTax Bool     A flag specifying whether the buying price includes/excludes tax.
isSold Boolean     Specifies whether the Combo Item can be sold or not. Default: false (cannot be sold).
saleIncomeAccountUid Int     Account for tracking sales. Only required if the item can be sold (isSold == true). Accounts used must be of type Income.
saleTaxCode String     Default tax code for sale.
saleCoSAccountUid Int     Accounts for tracking cost of sales. Required only if Combo Item is inventoried & for sale. Accounts used must be of type Cost of Sales.
sellingPrice Decimal     The default selling price for this Combo Item. Only applicable if the Combo Item is marked as sold.
isSellingPriceIncTax Boolean    
isVirtual Boolean     A flag that indicates this is an item you sell, that you haven’t bought or assembled as stock to make available for sale.
vType String     The type if this item is marked as virtual.
isVisible Boolean     A flag to set the Item to visible, for an example this can be used in your database so that Item is flagged to be displayed in your ecommerce product listings.
isVoucher Boolean     A flag specifying whether this item is treated as a voucher.
validFrom Date     When the voucher becomes effective.
validTo Date     When the voucher expires.
items     The items used for buidling this combo item

Item(Combo Item)

Field Type Max. Length Required? Notes
uid int     The uid of the item used for building this combo item.
quantity decimal     The quantity of the particular item used for building this combo item.
code string     The item code of the particular item.

InventoryAdjustment

Field Type Max. Length Required? Notes
uid Int Y Required for update
lastUpdatedUid String Y Required for update.
summary String 75   Brief summary for this adjustment.
tags String   Separate multiple tags by comma. Max length for each tag is 35 characters.
“tags” replaces “folderUid”.
requiresFollowUp Boolean    
items   Use item for all inventory adjustment items. Best practice is to split when the number reaches 100.

Item(InventoryAdjustment)

InventoryTransfer

Field Type Max. Length Required? Notes
quantity Decimal Y The quantity. Maximum of 3 decimals.
inventoryItemUid Int Y The inventory item for this adjustment line item.
accountUid Int Y The account for this adjustment line item.
unitPriceExclTax Decimal Y The unit price for this adjustment line item.
totalPriceExclTax Decimal Y The total price for this adjustment line item.
Field Type Max. Length Required? Notes
uid Int Y Required for update
lastUpdatedUid String Y Required for update.
summary String 75   Brief summary for this transfer.
tags String   Separate multiple tags by comma. Max length for each tag is 35 characters.
“tags” replaces “folderUid”.
requiresFollowUp Boolean    
items   Use item for all inventory transfer items. Best practice is to split when the number reaches 100.

Item(InventoryTransfer)

Field Type Max. Length Required? Notes
quantity Decimal Y The quantity. Maximum of 3 decimals.
inventoryItemUid Int Y The inventory item for this transfer line item.
unitPriceExclTax Decimal Y The unit price for this transfer line item.
totalPriceExclTax Decimal Y The total price for this transfer line item.

Journal

Field Type Max. Length Required? Notes
uid Int Y Required for update
lastUpdatedUid String Y Required for update.
summary String 75   Brief summary for this journal.
tags String   Separate multiple tags by comma. Max length for each tag is 35 characters.
“tags” replaces “folderUid”.
requiresFollowUp Boolean    
journalitems Y   You need to have at least two journal items that balance.
ccy String 3   The currency of the particular journal transaction.
autoPopulateFxRate Boolean     Indicates whether the FX rate for the journal was set automatically.
fcToBcFxRate Decimal     The Foreign Currency(FC) to Base Currency(BC) FX Rate. If you are setting the FX rate manually, and only have the BC to FC FX rate, then you should calculate the fcToBcFxRate for posting the transaction. For an example, if your base currency is AUD and 1 AUD = 0.89 USD, get the inverse by 1/0.89. So your fcToBcFxRate = 1.1235.
reference String 50  

JournalItem

Line item for journal.

Field Type Max. Length Required? Notes
accountUid Int   Y The account for this journal line item.
taxCode String     The tax code for this journal line item.
amount Decimal   Y The amount for this journal line item.
type String   Y Indicates the line item type. Either Credit or Debit.

TradingTerms

Field Type Max. Length Required? Notes
type Int   Y The trading terms type. 1 = Due In, 2 = EOM+(End Of Month + number of Days), 3 = COD(Cash On Delivery)
interval Int     Use with Due In and EOM+ types. Reflects the number of days/weeks/months.
intervalType Int     The interval type. 1 = Days, 2 = Weeks, 3 = Months.

Examples

Set due date as End of Month + 14 Days for an invoice

1
2
3
4
5

  <tradingTerms>
    <type>2</type>
    <interval>14</interval>
    <intervalType>1</intervalyType>
  </tradingTerms>

Set sale trading terms for a contact to be due in 2 weeks.

1
2
3
4
5

  <saleTradingTerms>
    <type>1</type>
    <interval>2</interval>
    <intervalType>2</intervalyType>
  </saleTradingTerms>

HTTP Delete

Deleting A Single Entity

To delete an entity, issue HTTP DELETE request to the server, passing the entity uid. The entity uid is specified in the URL using the uid query string parameter.

The system will perform its normal validation routine before delete the entity, such as ensuring that the entity is not referenced, etc. Errors will be returned if the validation fails.

Example

To delete a contact with uid 123, issue HTTP DELETE request to the following URL:

1
2

https://secure.saasu.com/webservices/rest/r1/contact?wsaccesskey=
test-888-888&fileuid=888888&uid=123

To delete an invoice with uid 123, issue HTTP DELETE request to the following URL:

1
2

https://secure.saasu.com/webservices/rest/r1/invoice?wsaccesskey=
test-888-888&fileuid=888888&&uid=123

Retrieving a Single Entity

To retrieve an entity, pass in the entity uid. The entity uid is specified in the URL using the uid query string parameter. For Invoice, you can specify an additional format query string parameter. Accepted formats are xml and pdf. Setting the format value to pdf will cause the invoice to be returned as PDF instead of XML.

Example

To retrieve a contact with uid 123

1

https://secure.saasu.com/webservices/rest/r1/contact?wsaccesskey=test-888-888&fileuid=888888&uid=123

To retrieve an invoice with uid 123 (output as XML)

1

https://secure.saasu.com/webservices/rest/r1/invoice?wsaccesskey=test-888-888&fileuid=888888&uid=123

To retrieve an invoice with uid 123 (output as PDF)

1

https://secure.saasu.com/webservices/rest/r1/invoice?wsaccesskey=test-888-888&fileuid=888888&uid=123&format=pdf

Syncing with Saasu
There are instances where API users need to keep data in Saasu synced with data from different systems. Most of the time this requires retrieving a list of records from Saasu and checking if there are any changes to perform necessary updates.

Example:
You have created a new contact in Saasu, and you need to sync the new contact with your CRM system.

  • Setup a process that checks for any contact updates in Saasu at a particular time of the day, for an example at 04:00 every day.
  • Every day at 04:00, the process will make a request to the ContactList resource to retrieve any contacts that were updated/inserted in Saasu after the last Sync. For an example, if the last sync ran at 04:00 on the 20th May 2009, then to get any updated/inserted contact records after the last sync make the following request: 
    1

    https://.../ContactList?WSAccessKey=xxx&FileUid=999&UtcLastmodifiedFrom=2009-05-20T04:00:00&UtcLastmodifiedTo=2009-05-21T04:00:00
  • Now that you have a list of contacts that have been updated/inserted in Saasu since the last sync, you can use the data to do the necessary INSERT or UPDATE tasks for the other system.

That’s all good, but what if there are any DELETED contacts in Saasu that I need to sync?

Good question, this is where the DeletedEntityList comes in handy. The DeletedEntityList resource will return a list of entities that were deleted from Saasu.
In this instance, to get a list of contacts that were deleted since the last sync, make the following request to the DeletedEntityList resource:

1

https://.../DeletedEntityList?WSAccessKey=XXX&FileUid=999&EntityTypeUid=10&UtcDeletedFrom=2009-05-20T04:00:00&UtcDeleteTo=2009-05-21T04:00:00

Deleted Entity List

Criteria:

QueryStringParameter Type Required? Notes
EntityTypeUid int Use:
4 = Sale
5 = Sale payment
7 = Purchase
8 = Purchase payment
10 = Contact
20 = Item
UtcDeletedFrom DateTime Must be used together with UtcDeletedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
UtcDeletedTo DateTime Must be used together with UtcDeletedFrom. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned
EntityTypeUid, EntityUid, User, Timestamp

Examples
Retrieve a list of deleted contacts.

1

https://.../DeletedEntityList?WSAccessKey=XXX&;FileUid=999&;EntityTypeUid=10

HTTP GET

The term queries refers to lists and reports in this documentation.

Criteria are embedded in the request URI using query string parameters. All criteria are joined using the AND logical operator, unless explicitly specified otherwise in this documentation.

InvoiceList

Criteria:

QueryStringParameter Type Notes
* TransactionType String Either s or p.
s = Sale.
p = Purchase.
PaidStatus String If not specified, will only return unpaid invoices. Valid values are: “paid”, “unpaid”, “all”.
InvoiceStatus Use:
Q = Quote
O = Order
I = Invoice. Filter won’t be applied if not specified.
InvoiceDateFrom Date Must be used together with InvoiceDateTo.
Returns invoices between the specified dates. If no date range specified returns transactions in last one month.
InvoiceDateTo Date
InvoiceDueDateFrom Date Must be used together with InvoiceDueDateTo.
Returns invoices that are due between the specified dates.
InvoiceDueDateTo Date
ContactUid Int
IncludeAllTags String Either use IncludeAllTags or IncludeAnyTags, but not both.
Separate tags by comma. Example:

1
2

http://.../invoicelist?wsaccesskey=xxx&fileuid=999&transactiontype=s&includealltags=
division1,division2.

This will return all sales that have BOTH “division1″ AND “division2″
tags applied.
IncludeAnyTags String Either use IncludeAllTags or IncludeAnyTags, but not both.
Separate tags by comma. e.g. http://…/invoicelist?wsaccesskey=xxx&fileuid=999&transactiontype=s&
includeanytags=division1,division2.
This will return all sales that have EITHER “division1″ OR
“division2″ tags applied.
ExcludeAllTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAnyTags”.
ExcludeAnyTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAllTags”
IsSent Boolean
InvoiceNumberBeginsWith String
PurchaseOrderNumberBeginsWith String
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8601 format.
Returns a list of invoices that were modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/invoicelist?wsaccesskey=xxx&fileuid=
999&transactiontype=s&utclastmodifiedfrom=
2009-03-06T02:20:00&utclastmodifiedto=
2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModfiedFrom. Usually, the DateTime would be in UTC, and ISO 8601 format.

* required

Deprecated filters and fields

The following filters are no longer supported:

  • FolderUid. Use IncludeAllTags, IncludeAnyTags, ExcludeAllTags or
    ExcludeAnyTags instead.

The following return fields have been deprecated: FolderUid, FolderName.

Fields Returned

InvoiceUid, LastUpdatedUid, TransactionType,
InvoiceDate, UtcFirstCreated, UtcLastModified, Summary, InvoiceNumber, PurchaseOrderNumber, DueDate,
Ccy, AutoPopulateFxRate, FcToBcFxRate, TotalAmountInclTax, PaymentCount, TotalAmountPaid, AmountOwed,
PaidStatus, RequiresFollowUp, IsSent,
InvoiceLayout, InvoiceStatus, InvoiceTypeUid,
ContactUid, ContactGivenName, ContactFamilyName, ContactOrganisationName,ShipToContactUid, ShipToContactFirstname, ShipToContactLastName, ShipToContactOrganisation
Tags

Examples

Retrieve a list of unpaid sale orders for contact 9

1
2

https://.../invoicelist?wsaccesskey=XXX&fileuid=999&transactiontype=
S&contactuid=9&invoicestatus=O&paidStatus=unpaid

InvoicePaymentList

Criteria

QueryStringParameter Type Required? Notes
TransactionType String Y Either SP or PP
SP = Sale Payment
PP = Purchase Payment
PaymentDateFrom Date If PaymentDateFrom and PaymentDateTo are both provided, payments paid/received between the specified dates will be returned.If PaymentDateFrom is provided but PaymentDateTo is not provided, payments with date >= payments will be returned.

If PaymentDateFrom is not provided but PaymentDateTo is provided, payments with date <= PaymentDateTo will be returned.
PaymentDateTo Date
DateClearedFrom Date If DateClearedFrom and DateClearedTo are both provided, payments cleared between the specified dates will be returned.If DateClearedFrom is provided but DateClearedTo is not provided, payments cleared date >= DateClearedFrom will be returned.

If DateClearedFrom is not provided but DateClearedTo is provided, payments cleared <= DateClearedTo will be returned.
DateClearedTo Date
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8601 format.
Returns a list of invoice payments that were modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/invoicepaymentlist?wsaccesskey=xxx&fileuid=999&transactiontype=sp&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModfiedFrom. Usually, the DateTime would be in UTC, and ISO 8601 format.
BankAccountUid Int The bank account where the payment is made or banked to.

Fields Returned

InvoicePaymentUid, LastUpdatedUid, PaymentDate, Ccy, AutoPopulateFxRate, FcToBcFxRate, UtcFirstCreated, UtcLastModified, DateCleared, Summary, Reference, BankAccountUid, BankAccountName, Amount

Example: Retrieve a list of sale payments dated between 1-Jul-05 to 30-Jun-06 banked to Westpac Account (BankAccountUid = 8101).

1
2

https://.../InvoicePaymentList?WSAccessKey=XXX&FileUid=999&TransactionType=SP&
BankAccountUid=8101&PaymentDateFrom=2005-07-01&PaymentDateTo=2006-06-30

ContactList
Criteria

QueryStringParameter Type Required? Notes
IncludeAllTags String Either use IncludeAllTags or IncludeAnyTags, but not both. Separate tags by comma.
IncludeAnyTags String Either use IncludeAllTags or IncludeAnyTags, but not both.
Separate tags by comma.
ExcludeAllTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAnyTags”.
ExcludeAnyTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAllTags”
IsActive Boolean
SearchFieldName String Valid values: OrganisationName, GivenName, FamilyName, EmailAddress or ContactID
SearchFieldNameBeginsWith String
Contact ID String
GivenName String Performs exact search by given name (a.k.a first name)
FamilyName String Performs exact search by family name (a.k.a. last name)
OrganisationName String Performs exact search by organisation name (a.k.a. company).
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8601 format.
Returns a list of contacts that were modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/contactlist?wsaccesskey=xxx&fileuid=999&givenname=james&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedFrom. Usually, the DateTime would be in UTC, and ISO 8601 format.

Deprecated filters and fields

The following filters are no longer supported: IndustryUid, StatusUid. Use IncludeAllTags, IncludeAnyTags, ExcludeAllTags or ExcludeAnyTags instead.

Fields Returned

ContactUid, UtcFirstCreated, UtcLastModified, LastUpdatedUid, Salutation, GivenName, MiddleInitials, FamilyName, DateOfBirth,
Organisation, OrganisationName, OrganisationABN, ABN,
OrganisationWebsite, OrganisationPosition, EmailAddress, WebsiteUrl, IsActive,
MainPhone, HomePhone, MobilePhone, OtherPhone, Fax,
Street, City, State, PostCode, Country,
OtherStreet, OtherCity, OtherState, OtherPostCode, OtherCountry,
ContactID,
AcceptDirectDeposit, DirectDepositAccountName, DirectDepositAccountBSB, DirectDepositAccountNumber,
AcceptCheque, ChequePayableTo,
Tags,
CustomField1, CustomField2, LinkedInPulicProfile, TwitterId, SkypeId, AutoSendStatement, IsPartner,
IsCustomer, IsSupplier, ContactManagerUid, SaleTradingTermsType, SaleTradingTermsInterval, SaleTradingTermsIntervalType,
PurchaseTradingTermsType, PurchaseTradingTermsInterval, PurchaseTradingTermsIntervalType, DefaultSaleDiscount, DefaultPurchaseDiscount

Examples

Retrieve a list prospects from IT industry (“Prospects” and “IT” are tags)

1

https://.../contactlist?wsaccesskey=xxx&fileuid=999&includealltags=prospects,it

Retrieve a list of contacts where the given name begins with j

1
2

https://.../contactlist?wsaccesskey=xxx&fileuid=999&&searchfieldname=
givenname&searchfieldnamebeginswith=j

Look up Carl O’Neil from O’Neil Capital

1
2

https://.../contactlist?wsaccesskey=xxx&fileuid=999&givenname=
carl&familyName=o'neil&organisationName=o'neil+capital

Look up contact by Contact ID

1

https://.../contactlist?wsaccesskey=xxx&fileuid=999&contactid=GLD879

TagList

Criteria:

QueryStringParameter Type Required? Notes
IsActive Boolean

Fields Returned

TagUid, Name, Frequency, IsActive, IsPopular,
IsFolder, IsActivity,
IsPM, IsConnector, IsInbuilt, IsCustomer,
IsProspect, IsPartner, IsSupplier

Note: IsFolder flag == IsReportTag

TransactionCategoryList (Chart of Accounts)

Criteria:

QueryStringParameter Type Required? Notes
Type String Valid value is one of the following:
Income, Expense, Asset, Equity, Liability, Other Income, Other Expense, Cost of Sales
IsActive Boolean
IsInbuilt Boolean Inbuilt Accounts are system-wide Accounts that are shared across all Files.

Fields Returned

TransactionCategoryUid, LastUpdatedUid, UtcFirstCreated, UtcLastModified, Type, Name, LedgerCode, DefaultTaxCode, IsActive, IsInbuilt

Examples

Retrieve a list of active expense Accounts that are not inbuil

1
2

https://.../TransactionCategoryList?WSAccessKey=XXX&FileUid=999&Type=
Expense&IsActive=true&IsInbuilt=false

BankAccountList

Criteria:

QueryStringParameter Type Required? Notes
Type String Valid value is one of the following:
Income, Expense, Asset, Equity, Liability, Other Income, Other Expense, Cost of Sales
IsActive Boolean
IsInbuilt Boolean Inbuilt Accounts are system-wide Accounts that are shared across all Files.

Fields Returned

BankAccountUid, LastUpdatedUid, UtcFirstCreated, UtcLastModified, Type, Name, LedgerCode, IsActive, IsInbuilt, DisplayName, BSB, AccountNumber

Examples

Retrieve a list of active bank accounts.

1

https://.../BankAccountList?WSAccessKey=XXX&FileUid=999&IsActive=true

InventoryItemList

NOTE: DEPRECATED – Use FullInventoryItemList instead

Criteria

QueryStringParameter Type Required? Notes
IsActive Boolean
CodeBeginsWith String
DescriptionBeginsWith String
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of inventory items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/inventoryitemlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

InventoryItemUid, LastUpdatedUid, UtcFirstCreated, UtcLastModified, Code, Description, IsActive, StockOnHand, CurrentValue, AverageCost, RrpInclTax, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVirtual, VType, IsVisibile, IsVoucher, ValidFrom, ValidTo

Examples

Retrieve a list of inventory items where the description begins with Pentium.

1
2

https://.../InventoryItemList?WSAccessKey=XXX&FileUid=
999&DescriptionBeginsWith=Pentium

FullInventoryItemList

Criteria

QueryStringParameter Type Required? Notes
IsActive Boolean
CodeBeginsWith String
DescriptionBeginsWith String
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of inventory items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/inventoryitemlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

InventoryItemUid, LastUpdatedUid, UtcFirstCreated, UtcLastModified, Code, Description, IsActive, StockOnHand, CurrentValue, AverageCost, RrpInclTax, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVirtual, VType, IsVisibile, IsVoucher, ValidFrom, ValidTo, IsInventoried, AssetAccountUid, QuantityOnOrder, QuantityCommitted, IsBought, PurchaseExpenseAccountUid, PurchaseTaxCode, MinimumStockLevel, PrimarySupplierContactUid, PrimarySupplierItemCode, DefaultReOrderQuantity, IsSold,
SaleIncomeAccountUid, SaleTaxCode, SaleCoSAccountUid, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVoucher, ValidFrom, ValidTo, IsVirtual, IsVisible, Notes

Examples:
Retrieve a list of inventory items where the description begins with Pentium.

1
2

https://.../FullInventoryItemList?WSAccessKey=XXX&FileUid=
999&DescriptionBeginsWith=Pentium

ComboItemList

NOTE: DEPRECATED – Use FullComboItemList instead

Criteria:

QueryStringParameter Type Required? Notes
IsActive Boolean
CodeBeginsWith String
DescriptionBeginsWith String
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of combo items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/comboitemlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

InventoryItemUid, LastUpdatedUid, UtcFirstCreated, UtcLastModified, Code, Description, IsActive, StockOnHand, CurrentValue, AverageCost, RrpInclTax, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVirtual, VType, IsVisibile, IsVoucher, ValidFrom, ValidTo

Examples:

Retrieve a list of combo items where the description begins with SOHO.

1

https://.../ComboItemList?WSAccessKey=XXX&FileUid=999&DescriptionBeginsWith=SOHO

FullComboItemList

Criteria

QueryStringParameter Type Required? Notes
IsActive Boolean
CodeBeginsWith String
DescriptionBeginsWith String
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of combo items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/comboitemlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

UtcFirstCreated, UtcLastModified, Code, Description, IsActive, StockOnHand, CurrentValue, AverageCost, RrpInclTax, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVirtual, VType, IsVisibile, IsVoucher, ValidFrom, ValidTo, IsInventoried, AssetAccountUid, QuantityOnOrder, QuantityCommitted, IsBought, PurchaseExpenseAccountUid, PurchaseTaxCode, MinimumStockLevel, PrimarySupplierContactUid, PrimarySupplierItemCode, DefaultReOrderQuantity, IsSold,
SaleIncomeAccountUid, SaleTaxCode, SaleCoSAccountUid, SellingPrice, IsSellingPriceIncTax, BuyingPrice, IsBuyingPriceIncTax, IsVoucher, ValidFrom, ValidTo, IsVirtual, IsVisible, Notes, Items, Item, Uid, Code, Quantity

Examples:
Retrieve a list of combo items where the description begins with SOHO.

1

https://.../FullComboItemList?WSAccessKey=XXX&FileUid=999&DescriptionBeginsWith=SOHO

InventoryAdjustmentList

Criteria:

QueryStringParameter Type Required? Notes
DateFrom DateTime
DateTo DateTime
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of inventory items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/inventoryAdjustmentlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

InventoryAdjustmentUid, Date, Summary, UtcFirstCreated, UtcLastModified, RequiresFollowUp

Examples:
Retrieve a list of inventory adjustments between 2009-06-06 and 2009-07-06.

1
2

https://.../InventoryAdjustmentList?WSAccessKey=XXX&FileUid=
999&DateFrom=2009-06-06&DateTo=2009-07-06

InventoryTransferList

Criteria:

QueryStringParameter Type Required? Notes
DateFrom DateTime
DateTo DateTime
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of inventory items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/inventoryTransferlist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned
InventoryTransferUid, Date, Summary, UtcFirstCreated, UtcLastModified, RequiresFollowUp

Examples:
Retrieve a list of inventory transfers between 2009-06-06 and 2009-07-06.

1
2

https://.../InventoryTransferList?WSAccessKey=XXX&FileUid=999&DateFrom=
2009-06-06&DateTo=2009-07-06

JournalList

Criteria:

QueryStringParameter Type Required? Notes
JournalDateFrom DateTime
JournalDateTo DateTime
IncludeAllTags String Either use IncludeAllTags or IncludeAnyTags, but not both. Separate tags by comma.
IncludeAnyTags String Either use IncludeAllTags or IncludeAnyTags, but not both.
Separate tags by comma.
ExcludeAllTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAnyTags”.
ExcludeAnyTags String Can be used in conjunction with “IncludeAllTags” or “IncludeAnyTags”
but not “ExcludeAllTags”
UtcLastModifiedFrom DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.
Returns a list of inventory items modified between UtcLastModifiedFrom and UtcLastModifiedTo.
e.g. http://…/journallist?wsaccesskey=xxx&fileuid=999&utclastmodifiedfrom=2009-03-06T02:20:00&utclastmodifiedto=2009-03-06T02:30:00
UtcLastModifiedTo DateTime Must be used together with UtcLastModifiedTo. Usually, the DateTime would be in UTC, and ISO 8061 format.

Fields Returned

TransactionType, UtcFirstCreated, UtcLastModified, Date, Summary, Tags, Ccy, AutoPopulateFxRate, FcToBcFxRate, RequiresFollowUp, JournalItems, JournalItem, AccountUid, TaxCode, Type, Amount

Examples

Returns a list of Journals between 2010-05-01 and 2010-05-05.

1

https://.../JournalList?WSAccessKey=XXX&FileUid=999&JournalDateFrom=2010-05-01&JournalDateTo=2010-05-05

TaxCodeList

Examples:
Returns a list of all tax codes in file.

1

https://.../TaxCodeList?WSAccessKey=XXX&;FileUid=999

HTTP Post

How to insert and update for each major entity.

Post tasks to the following URL:

1
2

https://[WSUrl]/tasks?wsccesskey=[WSAccessKey]&amp;fileuid=[FileUid]
substituting [WSUrl], [WSAccessKey], [FileUid] with valid values.

When inserting an entity (submitting an insert task) DO NOT specify the value of the uid element or set the value to 0.

When updating an entity (submitting an update task) provide the entity uid and lastUpdatedUid values. The LastUpdatedUid value identifies when the record was last updated. We require this value to be passed on update to ensure that no one updates the record since your last read operation. Make sure you include all elements as not including an element will lead to the existing value being cleared.

insertContact and updateContact

Inserts / updates Contact.

Field Type Max. Length Required? Notes
contact Contact Y The Contact to be inserted / updated.

Example: Insert Contact

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <insertContact>
    <contact uid="0">
      <salutation>Mr.</salutation>
      <givenName>John</givenName>
      <familyName>Smith</familyName>
      <organisationName>Saasy.tv</organisationName>
      <organisationAbn>777888999</organisationAbn>
      <organisationPosition>Director</organisationPosition>
      <email>john.smith@saasy.tv</email>
      <mainPhone>02 9999 9999</mainPhone>
      <mobilePhone>0444 444 444</mobilePhone>
      <contactID>XYZ123</contactID>
      <tags>Gold Prospect, Film</tags>
      <postalAddress>
        <street>3/33 Victory Av</street>
        <city>North Sydney</city>
        <state>NSW</state>
	<postCode>2000</postCode>
        <country>Australia</country>
      </postalAddress>
      <otherAddress>
        <street>111 Elizabeth street</street>
        <city>Sydney</city>
        <state>NSW</state>
	<postCode>2000</postCode>
        <country>Australia</country>
      </otherAddress>
      <isActive>true</isActive>
      <acceptDirectDeposit>false</acceptDirectDeposit>
      <directDepositAccountName>John Smith</directDepositAccountName>
      <directDepositBsb>000000</directDepositBsb>
      <directDepositAccountNumber>12345678</directDepositAccountNumber>
      <acceptCheque>false</acceptCheque>
      <customField1>This is custom field 1</customField1>
      <customField2>This is custom field 2</customField2>
      <twitterID>Contact twitter id</twitterID>
      <skypeID>Contact skype id</skypeID>
      <saleTradingTerms>
        <type>1</type>
        <interval>7</interval>
        <intervalType>1</intervalType>       
      </saleTradingTerms>
      <purchaseTradingTerms>
        <type>2</type>
        <interval>14</interval>
        <intervalType>1</intervalType>        
    </purchaseTradingTerms>
    <defaultSaleDiscount>15.75</defaultSaleDiscount>
    <defaultPurchaseDiscount>12.50</defaultPurchaseDiscount>
    </contact>
  </insertContact>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse>
    <insertContactResult insertedEntityUid="22729" lastUpdatedUid="AAAAAAAVA7s=" utcLastModified="2011-01-01T12:10:05"/>
  </tasksResponse>

Example: Update Contact

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateContact>
  <contact uid="22730" lastUpdatedUid="AAAAAAAVA8A=">
    <salutation>Mrs.</salutation>
    <givenName>Mary</givenName>
    <familyName>Smith</familyName>
    <organisationName>Mr. and Mrs. Smith</organisationName>
    <organisationAbn>67 093 453 886</organisationAbn>
    <organisationWebsite />
    <organisationPosition>Director</organisationPosition>
    <email>mary.smith@mrandmrssmith.com.au</email>
    <mainPhone>02 4444 4444</mainPhone>
    <homePhone />
    <mobilePhone>0444 444 444</mobilePhone>
    <tags>Customer, IT</tags>
    <postalAddress />
    <otherAddress />
    <isActive>true</isActive>
   </contact>
 </updateContact>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<updateContactResult updatedEntityUid="22730" lastUpdatedUid="AAAAAAAVA8E=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertTransactionCategory and updateTransactionCategory

Inserts / updates Account

Field Type Max. Length Required? Notes
transactionCategory TransactionCategory Y The TransactionCategory to be inserted / updated.

Example: Insert Account

Request content:

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <insertTransactionCategory>
  <transactionCategory uid="0">
   <type>Income</type>
   <name>Consulting Fees</name>
   <isActive>true</isActive>
   <ledgerCode>IT001</ledgerCode>
   <defaultTaxCode>G1</defaultTaxCode>
  </transactionCategory>
 </insertTransactionCategory>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
 <insertTransactionCategoryResult insertedEntityUid="10521" lastUpdatedUid="AAAAAAAVA8g=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Account

Request content:

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateTransactionCategory>
  <transactionCategory uid="10521" lastUpdatedUid="AAAAAAAVA8g=">
   <type>Income</type>
   <name>6a91110607244ef - For Testing Update</name>
   <isActive>true</isActive>
   <ledgerCode>IT001</ledgerCode>
   <defaultTaxCode>G1</defaultTaxCode>
  </transactionCategory>
 </updateTransactionCategory>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
 <updateTransactionCategoryResult updatedEntityUid="10522" lastUpdatedUid="AAAAAAAVA8o=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertBankAccount and updateBankAccount

Inserts / updates Bank Account.

Field Type Max. Length Required? Notes
bankAccount BankAccount Y The BankAccount to be inserted / updated.

Example: Insert Bank Account

NOTE: The displayName element is required.

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <insertBankAccount>
   <bankAccount uid="0">
   <type>Asset</type>
   <name>CBA</name>
   <isActive>true</isActive>
   <ledgerCode>BA001</ledgerCode>
   <displayName>CBA</displayName>
   <bsb>111-111</bsb>
   <accountNumber>12345-6789</accountNumber>
  </bankAccount>
 </insertBankAccount>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<insertBankAccountResult insertedEntityUid="10523" lastUpdatedUid="AAAAAAAVA8s=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Bank Account

Note: The displayName element is required.

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateBankAccount>
  <bankAccount uid="10523" lastUpdatedUid="AAAAAAAVA8s=">
    <type>Liability</type>
    <name>CBA</name>
    <isActive>true</isActive>
    <displayName>CBA 12345</displayName>
    <bsb>111-111</bsb>
    <accountNumber>12345-6789</accountNumber>
  </bankAccount>
 </updateBankAccount>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<updateBankAccountResult updatedEntityUid="10523" lastUpdatedUid="AAAAAAAVA80=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertInventoryItem and updateInventoryItem

Inserts / updates Inventory Item.

Field Type Max. Length Required? Notes
inventoryItem InventoryItem Y The InventotyItem to be inserted / updated.

Example: Insert Inventory Item

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <insertInventoryItem>
	<inventoryItem uid="0">     
	[[code]]czozMTpcIkNPREVfMGM4LTRhYjItOTMzMy0wODkwNjU5YjVkNTFcIjt7WyYqJl19[[/code]]
	<description>Description for 633638128318905000</description>
	<isActive>true</isActive>
	<notes>Notes for CODE_0c8-4ab2-9333-0890659b5d51</notes>
	<isInventoried>true</isInventoried>
	<assetAccountUid>87346</assetAccountUid>
	<stockOnHand>0</stockOnHand>
	<currentValue>0</currentValue>
	<isBought>true</isBought>
	<purchaseExpenseAccountUid>0</purchaseExpenseAccountUid>open
	<purchaseTaxCode>G11</purchaseTaxCode>
	<minimumStockLevel>99</minimumStockLevel>
	<primarySupplierContactUid>205235</primarySupplierContactUid>
	<primarySupplierItemCode>S_CODE</primarySupplierItemCode>
	<defaultReOrderQuantity>20</defaultReOrderQuantity>
	<buyingPrice>15</buyingPrice>
	<isBuyingPriceIncTax>true</isBuyingPriceIncTax>
	<isSold>true</isSold>
	<saleIncomeAccountUid>87349</saleIncomeAccountUid>
	<saleTaxCode>G1</saleTaxCode>
	<saleCoSAccountUid>87348</saleCoSAccountUid>
	<sellingPrice>7.75</sellingPrice>
	<isSellingPriceIncTax>true</isSellingPriceIncTax>
	<isVirtual>true</isVirtual>
	<vType>billing</vType>
	<isVisible>false</isVisible>
	<isVoucher>true</isVoucher>
	<validFrom>01/01/2010</validFrom>
	<validTo>01/12/2010</validTo>
	</inventoryItem>
  </insertInventoryItem>
</tasks>

Response:

1
2
3
4
5

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<insertInventoryItemResult insertedEntityUid="2047"
  lastUpdatedUid="ece9a802-0611-4a7a-8aad-30eaf8e09a39" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Inventory Item

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateInventoryItem>
  <inventoryItem uid="2047" lastUpdatedUid="ece9a802-0611-4a7a-8aad-30eaf8e09a39">
  [[code]]czozMTpcIkNPREVfMGM4LTRhYjItOTMzMy0wODkwNjU5YjVkNTFcIjt7WyYqJl19[[/code]]
  <description>e64f5a8030f645d - For Test Update - Updated</description>
  <isActive>true</isActive>
  <notes>Updated ....</notes>
  <isInventoried>true</isInventoried>
  <assetAccountUid>10526</assetAccountUid>
  <isBought>true</isBought>
  <purchaseExpenseAccountUid>0</purchaseExpenseAccountUid>
  <purchaseTaxCode>G11</purchaseTaxCode>
  <minimumStockLevel>99</minimumStockLevel>
  <primarySupplierContactUid>22732</primarySupplierContactUid>
  <primarySupplierItemCode>S_CODE</primarySupplierItemCode>
  <defaultReOrderQuantity>20</defaultReOrderQuantity>
  <isSold>true</isSold>
  <saleIncomeAccountUid>10528</saleIncomeAccountUid>
  <saleTaxCode>G1,G2</saleTaxCode>
  <saleCoSAccountUid>10527</saleCoSAccountUid>
  <sellingPrice>19.95</sellingPrice>
  <isSellingPriceIncTax>true</isSellingPriceIncTax>
  </inventoryItem>
 </updateInventoryItem>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
 <updateInventoryItemResult updatedEntityUid="2047" lastUpdatedUid="328b1df2-5cd0-47e4-8702-773e27259fb4" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertComboItem and updateComboItem

Inserts / updates Combo Item.

Field Type Max. Length Required? Notes
ComboItem ComboItem Y The Combo to be inserted / updated.

Example: Insert Combo Item

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <insertComboItem>
    <comboItem uid="0">
	  [[code]]czoxNDpcIkMgLSBhMjk3OGRkOC0yXCI7e1smKiZdfQ==[[/code]]
      <description>Insert Combo Item Test</description>
      <isActive>true</isActive>
      <notes>Combo item notes.</notes>
      <isInventoried>true</isInventoried>
      <assetAccountUid>198019</assetAccountUid>
      <stockOnHand>0</stockOnHand>
      <currentValue>0</currentValue>
      <quantityOnOrder>0</quantityOnOrder>
      <quantityCommitted>0</quantityCommitted>
      <isBought>true</isBought>
      <purchaseExpenseAccountUid>0</purchaseExpenseAccountUid>
      <purchaseTaxCode>G10</purchaseTaxCode>
      <minimumStockLevel>0</minimumStockLevel>
      <primarySupplierContactUid>693521</primarySupplierContactUid>
      <primarySupplierItemCode>ITOP090</primarySupplierItemCode>
      <defaultReOrderQuantity>10</defaultReOrderQuantity>
      <isSold>true</isSold>
      <saleIncomeAccountUid>198022</saleIncomeAccountUid>
      <saleTaxCode>G1</saleTaxCode>
      <saleCoSAccountUid>198021</saleCoSAccountUid>
      <sellingPrice>350.00</sellingPrice>
      <isSellingPriceIncTax>false</isSellingPriceIncTax>
      <buyingPrice>175.00</buyingPrice>
      <isBuyingPriceIncTax>false</isBuyingPriceIncTax>
      <isVoucher>true</isVoucher>
      <validFrom>2010-05-28T00:00:00</validFrom>
      <validTo>2010-12-28T00:00:00</validTo>
      <isVirtual>true</isVirtual>
      <vType>Virtual Voucher</vType>
      <isVisible>true</isVisible>
      <items>
        <item>
          <uid>221122</uid>
          [[code]]czoyMTpcIkFTVVMtM2RmLTYzZDhiYjU1OWYwOFwiO3tbJiomXX0=[[/code]]
          <quantity>1</quantity>
        </item>
        <item>
          <uid>336655</uid>
          [[code]]czoyMTpcIkNhdDUtM2RmLTYzZDhiYjU1OWYwOFwiO3tbJiomXX0=[[/code]]
          <quantity>1</quantity>
        </item>
      </items>
    </comboItem>
  </insertComboItem>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
	<insertComboItemResult insertedEntityUid="321654" lastUpdatedUid="ef6f1eae-2758-4b0e-a7a9-e6e11b56e0df" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Combo Item

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

<?xml version="1.0" encoding="utf-8"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <updateComboItem>
    <comboItem uid="321654" lastUpdatedUid="ef6f1eae-2758-4b0e-a7a9-e6e11b56e0df">
      [[code]]czoxMjpcIkMtYTI5NzhkZDgtMlwiO3tbJiomXX0=[[/code]]
      <description>Insert Combo Item Test</description>
      <isActive>true</isActive>
      <notes>Combo item notes.</notes>
      <isInventoried>true</isInventoried>
      <assetAccountUid>198019</assetAccountUid>
      <stockOnHand>0</stockOnHand>
      <currentValue>0</currentValue>
      <quantityOnOrder>0</quantityOnOrder>
      <quantityCommitted>0</quantityCommitted>
      <isBought>true</isBought>
      <purchaseExpenseAccountUid>0</purchaseExpenseAccountUid>
      <purchaseTaxCode>G10</purchaseTaxCode>
      <minimumStockLevel>0</minimumStockLevel>
      <primarySupplierContactUid>693521</primarySupplierContactUid>
      <primarySupplierItemCode>ITOP090</primarySupplierItemCode>
      <defaultReOrderQuantity>10</defaultReOrderQuantity>
      <isSold>true</isSold>
      <saleIncomeAccountUid>198022</saleIncomeAccountUid>
      <saleTaxCode>G1</saleTaxCode>
      <saleCoSAccountUid>198021</saleCoSAccountUid>      
      <sellingPrice>350.00</sellingPrice>
      <isSellingPriceIncTax>false</isSellingPriceIncTax>
      <buyingPrice>175.00</buyingPrice>
      <isBuyingPriceIncTax>false</isBuyingPriceIncTax>
      <isVoucher>true</isVoucher>
      <validFrom>2010-05-28T00:00:00</validFrom>
      <validTo>2010-12-28T00:00:00</validTo>
      <isVirtual>true</isVirtual>
      <vType>Virtual Voucher</vType>
      <isVisible>true</isVisible>
      <items>
        <item>
          <uid>334146</uid>
          [[code]]czoyMTpcIkFTVVMtM2RmLTYzZDhiYjU1OWYwOFwiO3tbJiomXX0=[[/code]]
          <quantity>1</quantity>
        </item>
        <item>
          <uid>334147</uid>
          [[code]]czoyMTpcIkNhdDUtM2RmLTYzZDhiYjU1OWYwOFwiO3tbJiomXX0=[[/code]]
          <quantity>1</quantity>
        </item>
        <item>
          <uid>14605</uid>
          [[code]]czozOlwiMTAwXCI7e1smKiZdfQ==[[/code]]
          <quantity>2</quantity>
        </item>
      </items>
    </comboItem>
  </updateComboItem>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
	<updateComboItemResult updatedEntityUid="321654" lastUpdatedUid="ad0a7f48-3b16-4696-a930-6dd303d3d5ea" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

buildComboItem

Builds specified number of units of a combo item.

Example: Build 12.25 units of combo item 1234

Request content:

1
2
3
4
5
6
7

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <buildComboItem>
    <uid>1234</uid>  <!-- The uid of the combo item to build -->
    <quantity>12.25</quantity> <!-- Number of units -->
  </buildComboItem>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <buildComboItemResult uid="1234" lastUpdatedUid="AAAAAAI5gv0=" />
</tasksResponse>

insertInvoice and updateInvoice

Inserts / updates Invoice. You can also ask the system to email PDF invoice at the same time.

NOTE: Saasu API does not handle amounts excluding tax. All amounts should be posted with the tax amount added to them.
This means the API user needs to work out the tax component based on the tax code(s), and add it to the unit price(s) of the invoice.

Field Type Max. Length Required? Notes
emailToContact Boolean Specifies whether to email the PDF invoice. Default: false (don’t email to contact).
templateUid Int Specifies the template to use for emailing the PDF invoice. If not specified, the default template will be used.
invoice Invoice Y The Invoice to be inserted / updated.
emailMessage EmailMessage See EmailMessage for details.

The result returned by insertInvoice task contains some extra fields in addition to standard “insertEntityUid” and “lastUpdatedUid” fields as described below.

Field Type Notes
insertedEntityUid Int
lastUpdatedUid String
sentToContact Boolean Indicates whether the invoice was emailed to contact.
generatedInvoiceNumber String When inserting a sale and the invoice number is set to <auto>, this field contains the system generated invoice number.
generatedPurchaseOrderNumber String When inserting a purchase and the purchase order number is set to , this fields contains the system generated purchase order number.

Example: Insert Service Sale & Email to Contact

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <insertInvoice emailToContact="true">
  <invoice uid="0">
   <transactionType>S</transactionType>
   <date>2005-09-30</date>
   <contactUid>22735</contactUid>
   <shipToContactUid>22735</shipToContactUid>
   <folderUid>0</folderUid>
   <summary>Test POST sale</summary>
   <notes>From REST</notes>
   <requiresFollowUp>false</requiresFollowUp>
   <dueOrExpiryDate>2005-12-30</dueOrExpiryDate>
   <layout>S</layout>
   <status>I</status>
   <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
   <purchaseOrderNumber>PO222</purchaseOrderNumber>
   <tradingTerms>
      <type>1</type>
      <interval>3</interval>
      <intervalType>3</intervalType>
   </tradingTerms>
   <invoiceItems>
    <serviceInvoiceItem>
     <description>Design and Development of REST WS</description>
     <accountUid>10555</accountUid>
     <taxCode>G1</taxCode>
     <totalAmountInclTax>2132.51</totalAmountInclTax>
    </serviceInvoiceItem>
    <serviceInvoiceItem>
     <description>Subscription to XYZ</description>
     <accountUid>10557</accountUid>
     <taxCode>G1</taxCode>
     <totalAmountInclTax>11.22</totalAmountInclTax>
    </serviceInvoiceItem>
   </invoiceItems>
   <quickPayment>
    <datePaid>2005-09-30</datePaid>
    <dateCleared>0001-01-01</dateCleared>
    <bankedToAccountUid>10562</bankedToAccountUid>
    <amount>100</amount>
    <reference>CASH</reference>
    <summary>Quick payment from Westpac.</summary>
   </quickPayment>
   <isSent>false</isSent>
  </invoice>
  <templateUid>4321</templateUid>
  <emailMessage>
   <from>test@saasu.com</from>
   <to>support@saasu.com</to>
   <subject>Invoice - Sent using NETaccounts OLA REST API (TestInsertAndEmail).</subject>
   <body>Insert Invoice then email.</body>
  </emailMessage>
 </insertInvoice>
</tasks>

Response:

1
2
3

<tasksResponse>
  <insertInvoiceResult insertedEntityUid="256872" lastUpdatedUid="AAAAAAAVBA4=" sentToContact="true" generatedInvoiceNumber="XYZ-2341"/>
</tasksResponse>

Example: Update Service Sale

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateInvoice emailToContact="false">
  <invoice uid="256875" lastUpdatedUid="AAAAAAAVBCc=">
  <transactionType>S</transactionType>
  <date>2005-09-15</date>
  <contactUid>22738</contactUid>
  <shipToContactUid>22738</contactUid>
  <tags>Online Sales</tags>
  <summary>Service Sale 2</summary>
  <requiresFollowUp>false</requiresFollowUp>
  <dueOrExpiryDate>2005-12-15</dueOrExpiryDate>
  <layout>S</layout>
  <status>I</status>
  <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
  <purchaseOrderNumber>PO123456789</purchaseOrderNumber>
   <tradingTerms>
      <type>1</type>
      <interval>3</interval>
      <intervalType>3</intervalType>
   </tradingTerms>
  <invoiceItems>
   <serviceInvoiceItem>
    <description>LINE 1 LINE 1 LINE 1</description>
    <accountUid>10568</accountUid>
    <taxCode>G1,G2</taxCode>
    <totalAmountInclTax>12345.12</totalAmountInclTax>
   </serviceInvoiceItem>
   <serviceInvoiceItem>
    <description>Testing</description>
    <accountUid>10567</accountUid>
    <taxCode>G7</taxCode>
    <totalAmountInclTax>-123.9</totalAmountInclTax>
   </serviceInvoiceItem>
   <serviceInvoiceItem>
    <description>Testing</description>
    <accountUid>10569</accountUid>
    <taxCode>G1</taxCode>
    <totalAmountInclTax>569.66</totalAmountInclTax>
   </serviceInvoiceItem>
  </invoiceItems>
  <quickPayment>
   <datePaid>0001-01-01</datePaid>
   <dateCleared>0001-01-01</dateCleared>
   <bankedToAccountUid>0</bankedToAccountUid>
   <amount>0</amount>
  </quickPayment>
  <isSent>false</isSent>
 </invoice>
</updateInvoice>
</tasks>

Response:

1
2
3
4
5

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<updateInvoiceResult updatedEntityUid="256875"
  lastUpdatedUid="AAAAAAAVBCw=" sentToContact="false" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Insert Foreign Currency Service Sale & Email to Contact

NOTE: Need to have Multi Currency turned ON for the file.
The example below set the FX rate manually. To set the FX rate automatically, use true and do not specify

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<insertInvoice emailToContact="true">
 <invoice uid="0">
  <transactionType>S</transactionType>
  <date>2005-09-30</date>
  <contactUid>22735</contactUid>
  <shipToContactUid>22735</shipToContactUid>
  <folderUid>0</folderUid>
  <summary>Test POST sale</summary>
  <notes>From REST</notes>
  <requiresFollowUp>false</requiresFollowUp>
  <dueOrExpiryDate>2005-12-01</dueOrExpiryDate>
  <ccy>USD</ccy>
  <autoPopulateFxRate>false</autoPopulateFxRate>
  <fcToBcFxRate>1.137640930</fcToBcFxRate>
  <layout>S</layout>
  <status>I</status>
  <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
  <purchaseOrderNumber>PO222</purchaseOrderNumber>
  <invoiceItems>
   <serviceInvoiceItem>
    <description>Design and Development of REST WS</description>
    <accountUid>10555</accountUid>
    <taxCode>G1</taxCode>
    <totalAmountInclTax>1000.50</totalAmountInclTax>
   </serviceInvoiceItem>
   <serviceInvoiceItem>
    <description>Subscription to XYZ</description>
    <accountUid>10557</accountUid>
    <taxCode>G1</taxCode>
    <totalAmountInclTax>11.22</totalAmountInclTax>
    </serviceInvoiceItem>
  </invoiceItems>
  <quickPayment>
   <datePaid>2005-09-30</datePaid>
   <dateCleared>0001-01-01</dateCleared>
   <bankedToAccountUid>10562</bankedToAccountUid>
   <amount>100</amount>
   <reference>CASH</reference>
   <summary>Quick payment from Westpac.</summary>
  </quickPayment>
  <isSent>false</isSent>
 </invoice>
 <emailMessage>
  <from>test@saasu.com</from>
  <to>support@saasu.com</to>
  <subject>Invoice - Sent using NETaccounts OLA REST API (TestInsertAndEmail).</subject>
  <body>Insert Invoice then email.</body>
 </emailMessage>
 </insertInvoice>
</tasks>

Response:

1
2
3

<tasksResponse>
<insertInvoiceResult insertedEntityUid="2546566" lastUpdatedUid="AAAAAAAHy6NM=" sentToContact="true" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Insert Item Sale

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <insertInvoice emailToContact="false">
    <invoice uid="0">
      <transactionType>S</transactionType>
      <date>2005-10-06</date>
      <contactUid>254091</contactUid>
      <shipToContactUid>254091</contactUid>
      <folderUid>0</folderUid>
      <summary>Test Insert Item Sale</summary>
      <notes>From REST</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <dueOrExpiryDate>2005-11-06</dueOrExpiryDate>
      <layout>I</layout>
      <status>I</status>
      <invoiceNumber>&lt;Auto Number&gt;</invoiceNumber>
      <purchaseOrderNumber>PO333</purchaseOrderNumber>
      <invoiceItems>
        <itemInvoiceItem>
          <quantity>2</quantity>
          <inventoryItemUid>73229</inventoryItemUid>
          <description>Asus Laptop</description>
          <taxCode>G1</taxCode>
          <unitPriceInclTax>1200.75</unitPriceInclTax>
          <percentageDiscount>12.50</percentageDiscount>
        </itemInvoiceItem>
        <itemInvoiceItem>
          <quantity>5.125</quantity>
          <inventoryItemUid>73230</inventoryItemUid>
          <description>Cat 5 Cable (in meter)</description>
          <taxCode>G1,G3</taxCode>
          <unitPriceInclTax>2.1234</unitPriceInclTax>
          <percentageDiscount>0</percentageDiscount>
        </itemInvoiceItem>
        <itemInvoiceItem>
          <quantity>3</quantity>
          <inventoryItemUid>73230</inventoryItemUid>
          <description>Cat 5 Cable (in meter)</description>
          <taxCode>G1,G2</taxCode>
          <unitPriceInclTax>5.125</unitPriceInclTax>
          <percentageDiscount>0</percentageDiscount>
        </itemInvoiceItem>
      </invoiceItems>
      <quickPayment>
        <datePaid>2005-10-06</datePaid>
        <dateCleared>0001-01-01</dateCleared>
        <bankedToAccountUid>92625</bankedToAccountUid>
        <amount>222.22</amount>
        <reference>C-001-023</reference>
      </quickPayment>
      <isSent>false</isSent>
    </invoice>
  </insertInvoice>
</tasks>

Response:

1
2
3

<tasksResponse>
  <insertInvoiceResult insertedEntityUid="1522302" lastUpdatedUid="AAAAAAEKXGg=" sentToContact="false" generatedInvoiceNumber="2015" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Email an Invoice

Summary

Emails the pdf invoice.

Field Type Max. Length Required? Notes
emailMessage emailMessage Y The email message to be sent.

Example: Email an invoice

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <emailPdfInvoice>
   <invoiceUid>123456</invoiceUid>
   <templateUid>4321</templateUid>
      <emailMessage>
       <from>johndoe@saasu.com</from>
       <to>janedoe@saasu.com</to>
       <cc></cc>
       <bcc></bcc>
       <subject>Invoice</subject>
       <body>Hi, please find the invoice attached.</body>
      </emailMessage>
   </emailPdfInvoice>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <emailPdfInvoiceResult sentToContact="true" />
</tasksResponse>

insertInvoicePayment and updateInvoicePayment

Summary:
Inserts / updates Invoice Payment.
The payment can be for sales or purchases.

Field Type Max. Length Required? Notes
invoicePayment InvoicePayment Y The InvoicePayment to be inserted / updated.

Example: Insert Payment for Purchases

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <insertInvoicePayment>
  <invoicePayment uid="0">
   <transactionType>PP</transactionType>
   <date>2005-12-20</date>
   <contactUid>0</contactUid>
   <reference>cf97d1a0-dec8-477a-9cc8-bbe0635ff87a</reference>
   <summary>Payment for 2 Outstanding Invoices</summary>
   <requiresFollowUp>false</requiresFollowUp>
   <paymentAccountUid>10588</paymentAccountUid>
   <dateCleared>0001-01-01</dateCleared>
   <fee>5.75</fee>
   <invoicePaymentItems>
    <invoicePaymentItem>
     <invoiceUid>256878</invoiceUid>
     <amount>20.05</amount>
    </invoicePaymentItem>
    <invoicePaymentItem>
     <invoiceUid>256877</invoiceUid>
     <amount>23.75</amount>
    </invoicePaymentItem>
   </invoicePaymentItems>
  </invoicePayment>
 </insertInvoicePayment>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
<insertInvoicePaymentResult insertedEntityUid="256879" lastUpdatedUid="AAAAAAAVBEg=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Invoice Payment for Sales

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?xml version="1.0" encoding="utf-8"?>
<tasks>
 <updateInvoicePayment>
  <invoicePayment uid="256883" lastUpdatedUid="AAAAAAAVBGU=">
   <transactionType>SP</transactionType>
   <date>2005-12-20</date>
   <contactUid>0</contactUid>
   <reference>2393d80b-093b-459e-927f-f71c7662dfd9</reference>
   <summary>Payment - Updated.</summary>
   <requiresFollowUp>false</requiresFollowUp>
   <paymentAccountUid>10601</paymentAccountUid>
   <dateCleared>0001-01-01</dateCleared>
   <fee>2.00</fee>
   <invoicePaymentItems>
    <invoicePaymentItem>
     <invoiceUid>256881</invoiceUid>
     <amount>30</amount>
    </invoicePaymentItem>
   </invoicePaymentItems>
  </invoicePayment>
 </updateInvoicePayment>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <updateInvoicePaymentResult updatedEntityUid="256883" lastUpdatedUid="AAAAAAAVBGY=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

Example: Insert Payment for Foreign Currency Sale.

NOTE: Need to have Multi Currency turned ON for the file.
The example below set the FX rate automatically. To set the FX rate manually, use <autoPopulateFxRate>false</autoPopulateFxRate> and specify the rate using </fcToBcFxRate>

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<?xml version="1.0" encoding="utf-8"?>
<tasks>
<insertInvoicePayment>
 <invoicePayment uid="0">
  <transactionType>SP</transactionType>
  <date>2010-02-22</date>
  <contactUid>0</contactUid>
  <reference>cf97d1a0-dec8-477a-9cc8-bbe0635ff87a</reference>
  <summary>Payment for Outstanding USD Invoice #1234</summary>
  <ccy>USD</ccy>
  <autoPopulateFxRate>true</autoPopulateFxRate>
  <requiresFollowUp>false</requiresFollowUp>
  <paymentAccountUid>10588</paymentAccountUid>
  <dateCleared>0001-01-01</dateCleared>
  <fee>5.00</fee>
  <invoicePaymentItems>
   <invoicePaymentItem>
    <invoiceUid>2546566</invoiceUid>
    <amount>1011.72</amount>
   </invoicePaymentItem>
  </invoicePaymentItems>
 </invoicePayment>
</insertInvoicePayment>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertInvoicePaymentResult insertedEntityUid="256879" lastUpdatedUid="AAAAAAAVBEg=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

insertInventoryAdjustment and updateInventoryAdjustment

Summary

Inserts / updates Inventory Adjustment

Field Type Max. Length Required? Notes
inventoryAdjustment inventoryAdjustment Y The InventoryAdjustment to be inserted / updated.

Example: Insert Inventory Adjustment

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <insertInventoryAdjustment>
    <inventoryAdjustment uid="0">
      <date>2009-07-17</date>
      <tags>IA, Test</tags>
      <summary>Test Inventory Adjustment CRUD</summary>
      <notes>Inventory Adjustmemt from API</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <items>
        <item>
          <quantity>1</quantity>
          <inventoryItemUid>142793</inventoryItemUid>
          <accountUid>111011</accountUid>
          <unitPriceExclTax>120.50</unitPriceExclTax>
          <totalPriceExclTax>120.50</totalPriceExclTax>
        </item>
        <item>
          <quantity>2</quantity>
          <inventoryItemUid>142792</inventoryItemUid>
          <accountUid>111019</accountUid>
          <unitPriceExclTax>100.25</unitPriceExclTax>
          <totalPriceExclTax>200.50</totalPriceExclTax>
        </item>
      </items>
    </inventoryAdjustment>
  </insertInventoryAdjustment>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertInventoryAdjustmentResult insertedEntityUid="1705574" lastUpdatedUid="AAAAAAFNR68=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Inventory Adjustment

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <updateInventoryAdjustment>
    <inventoryAdjustment uid="1705583" lastUpdatedUid="AAAAAAFNSA0=">
      <date>2009-07-17</date>
      <tags>IA, Test</tags>
      <summary>Updated inventory adjustment</summary>
      <notes>Inventory Adjustmemt from API</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <items>
        <item>
          <quantity>1</quantity>
          <inventoryItemUid>142797</inventoryItemUid>
          <accountUid>111024</accountUid>
          <unitPriceExclTax>120.50</unitPriceExclTax>
          <totalPriceExclTax>120.50</totalPriceExclTax>
        </item>
        <item>
          <quantity>2</quantity>
          <inventoryItemUid>142796</inventoryItemUid>
          <accountUid>111032</accountUid>
          <unitPriceExclTax>100.25</unitPriceExclTax>
          <totalPriceExclTax>200.50</totalPriceExclTax>
        </item>
      </items>
    </inventoryAdjustment>
  </updateInventoryAdjustment>
</tasks>

Response:

1
2
3

<tasksResponse>
  <updateInventoryAdjustmentResult updatedEntityUid="1705583" lastUpdatedUid="AAAAAAFNSBE=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertInventoryTransfer and updateInventoryTransfer

Inserts / updates Inventory Transfer:

Field Type Max. Length Required? Notes
inventoryTransfer inventoryTransfer Y The InventoryTransfer to be inserted / updated.

Example: Insert Inventory Transfer

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<?xml version="1.0" encoding="utf-8"?>
<tasks>
<insertInventoryTransfer>
<inventoryTransfer uid="0">
  <date>2009-07-17</date>
      <tags>IT, Test</tags>
      <summary>Test Inventory Transfer CRUD</summary>
      <notes>Inventory Transfer from API</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <items>
        <item>
          <quantity>-2</quantity>
          <inventoryItemUid>111300</inventoryItemUid>
          <unitPriceExclTax>120.50</unitPriceExclTax>
          <totalPriceExclTax>-241.00</totalPriceExclTax>
        </item>
        <item>
          <quantity>1</quantity>
          <inventoryItemUid>111298</inventoryItemUid>
          <unitPriceExclTax>241.00</unitPriceExclTax>
          <totalPriceExclTax>241.00</totalPriceExclTax>
        </item>
      </items>
    </inventoryTransfer>
  </insertInventoryTransfer>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertInventoryTransferResult insertedEntityUid="1671232" lastUpdatedUid="AAAAAAFE+qM=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Inventory Transfer

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <updateInventoryTransfer>
    <inventoryTransfer uid="1705556" lastUpdatedUid="AAAAAAFNRw0=">
      <date>2009-07-17</date>
      <tags>IT, Test</tags>
      <summary>Test Inventory Transfer CRUD</summary>
      <notes>Updated inventory transfer</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <items>
        <item>
          <quantity>-2</quantity>
          <inventoryItemUid>142790</inventoryItemUid>
          <unitPriceExclTax>120.50</unitPriceExclTax>
          <totalPriceExclTax>-241.00</totalPriceExclTax>
        </item>
        <item>
          <quantity>1</quantity>
          <inventoryItemUid>142788</inventoryItemUid>
          <unitPriceExclTax>241.00</unitPriceExclTax>
          <totalPriceExclTax>241.00</totalPriceExclTax>
        </item>
        <item>
          <quantity>-2</quantity>
          <inventoryItemUid>142789</inventoryItemUid>
          <unitPriceExclTax>60.50</unitPriceExclTax>
          <totalPriceExclTax>-121.00</totalPriceExclTax>
        </item>
        <item>
          <quantity>1</quantity>
          <inventoryItemUid>142790</inventoryItemUid>
          <unitPriceExclTax>121.00</unitPriceExclTax>
          <totalPriceExclTax>121.00</totalPriceExclTax>
        </item>
      </items>
    </inventoryTransfer>
  </updateInventoryTransfer>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <updateInventoryTransferResult updatedEntityUid="1705556" lastUpdatedUid="AAAAAAFNRxE=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

insertJournal and updateJournal

Criteria:

Field Type Max. Length Required? Notes
journal journal Y The Journal to be inserted / updated.

Example: Insert Journal

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <insertJournal>
    <journal uid="0">
      <date>2010-05-05</date>
      <tags>ABC, DEF</tags>
      <summary>Summary</summary>
      <notes>Notes</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <reference>#12345</reference>
      <journalItems>
        <journalItem>
          <accountUid>123456</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Credit</type>
        </journalItem>
        <journalItem>
          <accountUid>654321</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Debit</type>
        </journalItem>
      </journalItems>
    </journal>
  </insertJournal>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertJournalResult insertedEntityUid="123456789" lastUpdatedUid="AAAAAAIqlJg=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Example: Update Journal

Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <updateJournal>
    <journal uid="123456789" lastUpdatedUid="AAAAAAIqlJg=">
      <date>2010-05-05</date>
      <tags>ABC, DEF</tags>
      <summary>Add some summary.</summary>
      <notes>Updated journal.</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <reference>#12345</reference>
      <journalItems>
        <journalItem>
          <accountUid>184298</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Credit</type>
        </journalItem>
        <journalItem>
          <accountUid>184299</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Debit</type>
        </journalItem>
      </journalItems>
    </journal>
  </updateJournal>
</tasks>

Response:

1
2
3

<tasksResponse>
  <updateJournalResult updatedEntityUid="123456789" lastUpdatedUid="AAAAAAIqleo=" utcLastModified="2011-01-01T12:15:00"/>
</tasksResponse>

Example: Insert Foreign Currency Journal

NOTE: Need to have Multi Currency turned ON for the file.
The example below set the FX rate automatically. To set the FX rate manually, use false and specify the rate using
Request content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <insertJournal>
    <journal uid="0">
      <date>2010-05-05</date>
      <tags>ABC, DEF</tags>
      <summary>Summary</summary>
      <notes>Notes</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <ccy>USD</ccy>
      <autoPopulateFxRate>true</autoPopulateFxRate>
      <reference>#12345</reference>
      <journalItems>
        <journalItem>
          <accountUid>123456</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Credit</type>
        </journalItem>
        <journalItem>
          <accountUid>654321</accountUid>
          <taxCode>G11</taxCode>
          <amount>123.45</amount>
          <type>Debit</type>
        </journalItem>
      </journalItems>
    </journal>
  </insertJournal>
</tasks>

Response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertJournalResult insertedEntityUid="00001110000" lastUpdatedUid="AAAAAAIqpKc=" utcLastModified="2011-01-01T12:10:05"/>
</tasksResponse>

Activities

Supported fields:

Field Type Max. Length Required? Notes
uid Int   Y Required for update.
lastUpdatedUid String   Y Required for update.
utcFirstCreated DateTime   N  
utcLastModified DateTime   N  
type String   Y Activity type. Valid values: All tags with activity flag set to true.
done Boolean   N
title String 128 Y
details String N
due Date N
lastModified DateTime N
owner Email N Owner/user responsible for this activity. User must have access to the file where this activity belongs to.
attachedToType String N Attach this activity to other entity types. Valid values are: Contact, Employee, Sale and Purchase.
attachedToUid String N Entity uid where this activity is attached to.

Get an Activity
Request: GET https://[WSUrl]/Activity?wsaccesskey=[WSAccessKey]&fileuid=[FileUid]&uid=[ActivityUid]

Sample response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?xml version="1.0" encoding="utf-8"?>
<activityResponse>
  <activity uid="28749" lastUpdatedUid="AAAAAAJRdpQ=">
	<utcFirstCreated>2011-01-01T10:25:30</utcFirstCreated>
	<utcLastModified>2011-01-01T10:25:30</utcLastModified>
    <type>Meeting</type>
    <done>false</done>
    <due>2020-07-01</due>
    <modified>2011-01-01T10:25:30</modified>
    <title>Meeting with John Doe.</title>
    <details>To Discuss: 
		- Strategy for implementing new CRM, the stages.
		- Integrating the accounting software with shopping cart.
		- Upgrading the assembly line for increased productivity.</details>
    <owner>someone@saasu.com</owner>
    <attachedToType>Employee</attachedToType>
    <attachedToUid>432278</attachedToUid>
  </activity>
</activityResponse>

Insert an Activity

Sample request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <insertActivity>
    <activity uid="0">
      <type>Meeting</type>
      <done>false</done>
      <title>Meeting with John Doe.</title>
      <details>To Discuss: 
		- Strategy for implementing new CRM, the stages.
		- Integrating the accounting software with shopping cart.
		- Upgrading the assembly line for increased productivity.</details>
      <due>2020-07-01</due>
      <lastModified>0001-01-01T00:00:00</lastModified>
      <owner>someone@saasu.com</owner>
      <attachedToType>Employee</attachedToType>
      <attachedToUid>432278</attachedToUid>
    </activity>
  </insertActivity>
</tasks>

Sample response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <insertActivityResult insertedEntityUid="28749" lastUpdatedUid="AAAAAAJRdpQ=" utcLastModified="2011-01-01T10:25:30"/>
</tasksResponse>

Update an Activity

Sample request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?xml version="1.0" encoding="utf-16"?>
<tasks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <updateActivity>
    <activity uid="28755" lastUpdatedUid="AAAAAAJRpoU=">
      <type>Note</type>
      <done>false</done>
      <title>A nee Title.</title>
      <details>To Discuss: 
		- Strategy for implementing new CRM, the stages.
		- Integrating the accounting software with shopping cart.
		- Upgrading the assembly line for increased productivity.</details>
      <due>2020-07-01</due>
      <lastModified>0001-01-01T00:00:00</lastModified>
      <owner>api@saasu.com</owner>
    </activity>
  </updateActivity>
</tasks>

Sample response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<tasksResponse>
  <updateActivityResult updatedEntityUid="28755" lastUpdatedUid="AAAAAAJRpoc=" utcLastModified="2011-01-01T10:30:30"/>
</tasksResponse>

Delete an Activity
Request: DELETE https://[WSUrl]/Activity?wsaccesskey=[WSAccessKey]&fileuid=[FileUid]&uid=[ActivityUid]
Sample response:

1
2
3
4

<?xml version="1.0" encoding="utf-8"?>
<activityResponse>
  <deleteResult uid="28751" />
</activityResponse>

Get a list of Activities

Supported search criteria:

QueryStringParameter Type Notes
type String Activity type. Valid values: All tags with activity flag set to true.
status String Valid values: todo, done, overdue
owner String User’s email.
search String The search text.
datetype String Valid values: due, modified
periodtype String
attachedtotype String
attachedtouid Int
datefrom DateTime
dateto DateTime
includealltags String
includeanytags String
excludealltags String
excludeanytags String

Get to-do’s for a specific user

https://[WSAccessKey]/ActivityList?wsaccesskey=[WSAccessKey]&fileuid=[FileUid]&status=todo&owner=api%40saasu.com

Get activities attached to a specific contact

https://[WSAccessKey]/ActivityList?wsaccesskey=[WSAccessKey]&fileuid=[FileUid]&attachedtotype=contact&attachedtouid=123456

Get activities modified between certain period (UTC):

https://[WSAccessKey]/ActivityList?wsaccesskey=[WSAccessKey]&fileuid=[FileUid]&datetype=modified&owner=api%40saasu.com&datefrom=2010-06-18T05%3a38%3a46&DateTo=2010-06-18T05%3a43%3a56

Reports

Saasu’s next area of API development is in reporting. We have enabled the first and most requested report, statements.

Contact Statement

Get PDF contact statement report.

Request URL:

1

https://secure.saasu.com/webservices/rest/r1/contactstatementreport?wsaccesskey={YourWSAccessKey}&fileuid={YourFileUid}&contactuid={ContactUid}&datefrom={DateFrom}&dateto={DateTo}&format=pdf

All query-strings specified above are required.

Known Issues

Unformatted XML
When posting XML for a POST task, make sure the XML is formatted as shown in the examples i.e: a line break after each XML element. We are working on enhancing our serializers to handle unformatted XML at the moment and the fix will be available soon.

Pagination
We don’t page result sets at the moment. If you wish to retrieve large amounts of data do so in small blocks by using appropriate filters for the data being retrieved. We will introduce pagination in a future release.

Fair Play Limits for API

Fair play limits are how we keep the API free. Saasu loves a free API and we want to keep it that way. So we do ask that you play fair and don’t send us too many requests or inefficient ones. We have the following fair play rules with respect to the use of the API per File:

  • Maximum of 5 requests per second.
  • Maximum of 2,000 requests per day.
  • All synchronization activities must rely on Last Modified where this is supported in the API.
  • If you are making hundreds of requests at once, insert a minimum of 2 seconds delay for every 50 requests.
  • When sending a multiple task request limit the number of tasks to a maximum of 50.

If Saasu observes excessive API requests above the limits, Saasu may temporarily disable API access until the request approach is altered or defects in your code are resolved by you.

REST Clients for MS.Net

Our REST client is an abstraction layer for accessing the Saasu REST Web Service. Contains data transfer objects (DTO) and proxy classes, which encapsulate data and method calls to remote REST WS API. Use them as if you were working with local classes.

So why use it? It’s easier to work with classes rather than direct XML. It helps speed up integrating your application with Saasu if you’re using MS.NET.

Download Client and Sample App

Check config files (App.config and Web.config), replace WSAccessKey and FileUid with your own before running the nunittests and sample app.

Using the .NET API

The API contains 5 namespaces.

Your config file settings (web.config and/or app.config)

You will need to make some additions to your config file:

1. Add the following lines to your configSections:

1
2
3
4
5
6

<configSections>
  <sectionGroup name="ola.restclient">
    <section name="proxySettings" type="System.Configuration.NameValueSectionHandler,
    System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  </sectionGroup>
</configSections>

2.Declare the config values for proxySettings. Add the following lines to your config file (Use the provided values for each entry. The values provided here are for illustration purpose only).

1
2
3
4
5
6
7

<ola.restclient>
  <proxySettings>
    <add key="baseUri" value="https://secure.saasu.com/webservices/rest/r1/" />
    <add key="wsAccessKey" value="TEST-REST-API" />
    <add key="fileUid" value="99999" />
  </proxySettings>
</ola.restclient>

Simple CRUD Operations
When working with entity one at a time, you probably want to use the proxy class because it is simpler to use. The proxy class makes it easy to perform CRUD operations.

To insert/update an entity
1. Instantiate the entity dto and populate it with the required data.
2. Instantiate the entity proxy class and call the insert/update method passing the dto. Entity Uid, which identifies each entity, is not required on insert, but required on update.

Example: To insert an Account

1
2
3
4
5
6
7
8
9
10
11
12

//
// Step 1: Instantiate the entity dto and populate it with the required data.
//
TransactionCategoryDto dto = new TransactionCategoryDto();
dto.Type = AccountType.Income;
dto.Name = "Consulting Fees";
//
// Step 2: Instantiate the proxy class and call the insert method
// passing the dto.
//
CrudProxy proxy = new TransactionCategoryProxy();
proxy.Insert(dto);

Example: To update an Account

1
2
3
4
5
6
7

TransactionCategoryDto dto = this.GetTransactionCategoryToUpdate();
dto.Type = AccountType.Asset;
dto.Name = "Inventory";
//
// The dto.Uid must be > 0 when update.
//
new TransactionCategoryProxy().Update(dto);

Notes:

  • The WSAccessKey and FileUid are set when you instantiate the proxy class. Their values are read from the config file.
  • If you need to change the WsAccessKey or FileUid on-the-fly, you can do so by setting the appropriate properties of the proxy class. E.g. proxy.FileUid = 99;
  • Do not set the entity uid when you call the insert method. The uid will be set with a value generated by the system if the insert operation is completed successfully.

To retrieve an entity

Instantiate the entity proxy class, and call the get by uid method passing the entity uid.
E.g. To retrieve an Account with uid 23456 from your file

1
2

CrudProxy proxy = new TransactionCategoryProxy();
TransactionCategoryDto dto = (TransactionCategoryDto) proxy.GetByUid(23456);

To delete an entity
Instantiate the entity proxy class, and call the delete by uid method passing the entity uid. E.g. to delete an Account with uid 23456 from your file

1

new TransactionCategoryProxy().Delete(23456);

Queries (Lists and Reports)
You can still use the proxy class for performing queries. To perform a query:

  • Build the query by adding a search criterion to a NameValueCollection object.
  • Instantiate the proxy class and call the find method passing this query object.

E.g. to find a list of unpaid sales dated between 1-Jul-05 to 31-Dec-05 for contact with uid 779, you would write:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

//
// Step 1: Build query object (criteria are "AND-ed").
//
NameValueCollection queries = new NameValueCollection();
queries.Add("TransactionType", TransactionType.Sale);
queries.Add("PaidStatus", "unpaid");
queries.Add("InvoiceDateFrom", "1-Jul-05");
queries.Add("InvoiceDateTo", "31-Dec-05");
queries.Add("ContactUid", "779");
"TotalAmountInclTax,AmountOwed");
//
// Step 2: Instantiate proxy class and call the find method.
//
InvoiceProxy proxy = new InvoiceProxy();
XmlDocument list = proxy.Find(queries);

Tasks

Proxy classes are ideal if you only deal with one entity or operation at a time. However, there are times that where you probably will need to insert multiple invoices at once into your file. Submitting the invoice one by one to the server is slow and inefficient because of overheads caused by multiple remote calls.

In this scenario, use TasksRunner to submit multiple tasks to the server at once. You can submit any tasks in a single request. They can be mixed as long as the tasks are supported by the OLA REST API.

To submit various tasks in a single request:

  • Instantiate a TasksRunner class.
  • Add tasks to task runner object.
  • Call the execute method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

. . .
public void TestTasksRunner()
{
//
// Step 1: Instantiate TasksRunner
//
TasksRunner tasksRunner = new TasksRunner();
//
// Step 2: Add tasks.
//
tasksRunner.Tasks.Add(this.GetUpdateContactTask());
tasksRunner.Tasks.Add(this.GetInsertSaleTask1());
tasksRunner.Tasks.Add(this.GetInsertSaleTask2());
//
// Step 3: Call the execute method.
// NOTE: Check the response and results returned for errors.
//
TasksResponse response = tasksRunner.Execute();
}
public ITask GetUpdateContactTask()
{
ContactDto contactToUpdate = new ContactDto();
contactDto.Uid = 88888;
contactDto.GivenName = "Mary";
contactDto.FamilyName = "Smith";
IUpdateTask task = new UpdateContactTask();
task.EntityToUpdate = contactToUpdate;
return task;
}
public ITask GetInsertSaleTask1()
{
nvoiceDto dto = new InvoiceDto(TransactionType.Sale, InvoiceLayout.Service);
dto.Date = DateTime.Parse("30-Sep-05");
dto.ContactUid = this.MrSmith.Uid;
dto.Summary = "Test POST sale";
dto.Status = InvoiceStatus.Invoice;
dto.InvoiceNumber = "<auto>";
. . .
serviceInvoiceItemDto item = new serviceInvoiceItemDto();
item.Description = "Design &amp; Development of REST WS";
item.AccountUid = this.IncomeService.Uid;
item.TaxCode = TaxCode.SaleInclGst;
item.TotalAmountInclTax = 2132.51M;
dto.Items.Add(item);
. . .
return dto;
}</auto>
. . .

Terminology

  • API: Application Programming Interface.
  • CRUD: Create, read, update, and delete operations.
  • DTO: Data Transfer Object
  • Entity: Refers to things such as Contact, Account, Bank Account, etc.
  • OLA: Stands for Online Accounting. Used throughout the document to refer to Saasu Online Accounting system.
  • REST: Representational State Transfer.
  • Transaction: More specialised form of entity. E.g. Invoice, InvoicePayment, Bank Transfer, Inventory Adjustment.
  • UID: Unique Identifier.
  • WS: Web Service.
  • WSAccessKey: Web Service Access Key, which is required to access Saasu Web Services.
  • WSAPI: Web Services Application Programming Interface.

Table of Contents

  1. Introduction
  2. Entities
  3. HTTP Delete
  4. HTTP GET
  5. HTTP Post
  6. Activities
  7. Reports
  8. Known Issues
  9. Fair Play Limits for API
  10. REST Clients for MS.Net
  11. Terminology

template